Ubuntu desktop documentation scope and location

[Connor Imes]

I'd like to add some comments regarding the two wikis.

First, my recollection is that the Ubuntu wiki (wiki.ubuntu.com) is not 
really intended for user help documentation, but has been used for team 
organization (including LoCos), development-related docs and 
coordination, personal wiki pages, and perhaps even as a catch-all for 
anything not documentation-related that needed collaborative editing.  
That's not to say that people haven't put documentation there, though.  
This wiki is such a beast it may be impractical to overhaul with any 
real coherence, but I'd be curious if folks have proposals.  Also, I'm 
not really sure this wiki is (or should be) the documentation team's 
responsibility anyway.

In contrast, the community help wiki (help.ubuntu.com/community) is 
intended for collaborative editing of user documentation beyond the more 
formal system docs, server guide, and software man pages (IIRC, 
manpages.ubuntu.com didn't arrive until many years later). We've made 
various attempts over the years to improve its organization and flow, 
identify the most important pages, classify page contents and quality 
with tags, and eliminate duplicate, low-quality, and other pages deemed 
inappropriate for the help wiki.  My last major effort here was 5 or 6 
years ago, though - it was a huge time sink and I still wasn't anywhere 
close to making it through all the pages before other priorities forced 
the effort to the backburner.  That said, it may be practical to 
overhaul (or move to a new format) this wiki, but I think would require 
considerable effort even just to triage pages.

A final note: spam has previously been a problem that forced us to limit 
editing to approved documentation team members.  This naturally had a 
chilling effect on the greater community's contributions, which leads to 
stagnation.  I don't know how to solve this problem, but it's something 
to consider if you want to move to a different platform.  Also consider 
that wiki pages have been around for a long time and you should have an 
intelligent page forwarding approach if you're going to move to a new 
platform, otherwise you'll break 15+ years of web links.

Cheers,
-Connor

On 4/12/2022 11:20 AM, Daniele Procida wrote:
> Greetings all. I’ve been on annual leave for a few days, so I am just catching up.
>
> I’ve left individuals cc’d but do remove yourselves if you prefer.
>
> Thanks Heather for taking an interest in this topic. I think there are probably a few questions I can clear up here.
>
> The first thing is to reassure everyone that there are no plans to do anything to the main "Official Ubuntu documentation”, as found at help.ubuntu.com.
>
> Heather mentioned conversations about replacing existing wikis with Discourse-based documentation, but that applies to the "Community help wiki”  at help.ubuntu.com/community (note the URL - I know it’s at a confusing location), and to wiki.ubuntu.com (“The Ubuntu wiki”).
>
> Here’s a little overview of some of the relevant properties:
>
> help.ubuntu.com
> Name: Official Ubuntu documentation
> Maintained in: deb packages in the Ubuntu distribution.
> Documentation system: Mallard
> Contribution: via Launchpad
>
> help.ubuntu.com/community
> Name: Community help wiki
> Maintained in: MoinMoin wiki
>
> wiki.ubuntu.com
> Name: Ubuntu wiki
> Maintained in: MoinMoin wiki
>
> https://ubuntu.com/server/docs
> Name: Ubuntu server guide
> Maintained in: Discourse
>
> manpages.ubuntu.com
> Name: Ubuntu manpages
> Maintained in: the source of respective packages.
>
> Just to repeat: there will be no workflow changes, or changes that affect contributors, to Official Ubuntu documentation at help.ubuntu.com, without careful prior consultation with the community.
>
> The two wiki properties are in a very problematic state however. The community has invested a great deal of effort into them. We will need an additional significant effort to get that all material, and the platform hosting it, into a state that is worthy of the community’s past and on-going contributions.
>
> As Heather noted, it’s very likely that the new platform for maintaining that material will be Discourse, as used by the Ubuntu server guide. (There are various questions here, for example about how that material should be integrated with the “official” help.ubuntu.com content, but these are problems that are not going to be addressed on the fly - they’re also quite knotty issues.)
>
>>>>> May be worth mentioning this page:
>>>>>
>>>>> https://help.ubuntu.com/rst
>>>>>
>>>>> It originates from a google docs document. So if you are in a
>>>>> hurry, that's one possibility as a temporary solution.
> Gunnar, are you able to tell me more about this? Despite my previous extensive researches, this is a publishing pattern that is new to me. Are there other examples of this? (It’s also a problematic example, as it breaks the navigation links (cf. the “Official documentation” link at the top.)
>
> As for the original question of where to place the Active Directory material that Heather was asking about, it does seem from reading other comments in this thread that the Server guide is indeed the most suitable place for it (rather than the help.ubuntu.com/community wiki as I previously suggested).
>
> Three important things to note at this stage.
>
> Nothing dramatic will happen without community consultation.
>
> We’re keenly aware of some of the problem structures in the documentation properties, and significant issues with content, and there will be a large, co-ordinated effort to address that. I can’t say when though, sorry.
>
> In the meantime, we need not to make additional work for ourselves. The help.ubuntu.com/community wiki is not a thing of beauty, but it exists and it’s a known safe place for Ubuntu desktop documentation (that can’t be easily created via Mallard) to go. I would not like new properties or ad-hoc places for documentation to be created without co-ordination.
>
> Regards,
>
> Daniele