Ubuntu desktop documentation scope and location

Fri Apr 8 18:15:45 UTC 2022

Hey Gunnar,

On 4/7/22 16:06, Gunnar Hjalmarsson wrote:
> Hi again Heather!
> 
> On 2022-04-07 20:13, Heather Ellsworth wrote:
>> Thank you both so much for the clear reasoning on why the desktop
>> guide should remain tracking upstream closely and packaged as a deb.
>> The huge value of translations and the need for that was not as
>> obvious to me but it is now.
>>
>> However, as far as representing it on a website, I would recommend us
>> pursuing one of the two options:
>> 1. using the existing help.ubuntu.com, make something that looks a
>> bit more modern with stylesheets.
> 
> That's what I think we should do. Btw, the domain can well be changed to 
> better fit the structure of other Ubuntu documentation. What I'm arguing 
> for is to keep the Mallard XML syntax to be able to collaborate 
> efficiently with the GNOME Help team and preserve the translations.
> 

Ok sounds great. I had some offline discussions and the point of 
translations just can't be worked around. I think leaving the desktop 
guide alone is great and we should do that. So we are on the same page. 
Good to know that it is not tied to the domain or wiki itself.

>> This option keeps us on the wiki that has the epic benefit of not
>> doing a migration at all, but does require efforts on a technology
>> that Canonical seems to be trying to leave behind.
> 
> No, no. The future of the Community Help Wiki is a totally different 
> matter. The desktop guide is not tied to the Community Help Wiki at all. 
> They just happen to reside under the same domain currently.
> 
>> 2. looking into a discourse api that would publish ubuntu-help. The
>> downside of this is the effort going into a migration: the
>> investigation and implementation of tooling to lubricate the
>> migration. The benefit is that it would look more consistent with our
>> other discourse pages.
> 
> The latter may be true. The structure for helping the visitors to 
> navigate between the pages differs indeed between discourse generated 
> documentation and the desktop guide. Both ways make sense IMO.
> 
> But I still think it would be crazy to involve discourse for the web 
> publishing. Once the Mallard pages have been created, converting them to 
> HTML and applying a stylesheet including the header is easy. We use some 
> GNOME tools to do it.
> 
> And, again, I suppose we would loose the translations. Please note that 
> it's not only the version of the desktop guide on the hard disk which is 
> made available in many languages. That's true also for the published 
> version. Example:
> 
> https://help.ubuntu.com/stable/ubuntu-help/index.html.de
> 
> So I think the downsides of involving discourse for the desktop guide 
> outweighs the benefit you mention.

Yep I agree. I hadn't thought of translations and I think that can't be 
lost. There isn't a discourse answer for translations that I can find; I 
asked around the other documentation folks on the various canonical 
teams. There is an important need for offline documentation in lots of 
translations that can't be compromised.

I'm kind of surprised there isn't any translation for the server guide.

> 
>>> 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.
>>
>> Yes, we could copy/paste into a document and host it on help.u.c...
>> something like help.ubuntu.com/adsys. I'd like to embark on this
>> option as a last resort because again I feel like it is the wrong
>> place ultimately.
> 
> Probably the wrong place, yes. Please see it as an example of a google 
> docs document which was adapted to fit an existing structure.

Yep and thanks for the example. I may indeed need it :)

I've also found another tool that could help:
https://www.markdownguide.org/tools/google-docs-to-markdown/

> 
>> Also if we stylized the page to look nicer and newer, then it doesn't
>> match with the rest of the stuff in the domain :/
> 
> Well, if we created a new modern header for that page, we could (should) 
> apply it to the rest of the domain too. Including the wiki. (But 
> excluding the published docs for previous releases, I think.)

Yep, that all sounds good. I do not have any CSS experience, but can 
seek out some help from the Canonical web and design team for this. I'll 
reach out to them  see what their thoughts are on some modern updates :)

>>> Actually we recently talked about if from another angle but
>>> screenshots. Jon Duncan, a new docs team member, reached out to the
>>> desktop team through this topic:
>>>
>>> https://discourse.ubuntu.com/t/27335
>>>
>>> And Jeremy provided an extensive list of Ubuntu changes. But that's
>>> something to consider for coming cycles.
>>
>> Yes I saw this from other recent email threads, and I completely
>> agree we should document these differences.
>>
>> The problem I'm stuck with is *where* to document desktop things,
>> outside of the desktop guide.
> 
> Why would we document desktop things outside of the desktop guide? The 
> current plan is to somehow adapt the desktop guide to include the most 
> important Ubuntu differences.

We would document desktop things outside of the desktop guide because 
the usage of "desktop things" is broader to include 3 audiences: the 
user guide, enterprise admins, and developers. The documentation for the 
enterprise admins and developers does not exist yet, or exists somewhere 
on wiki.ubuntu.com, scattered among pages, and is likely outdated and in 
need of an update anyways.

The user guide is mostly the desktop guide, but we can add other 
important things too, like the Ubuntu differences identified by Jon's 
discourse post, info on core snaps, etc.

Enterprise documentation would cover things like Active Directory with 
Ubuntu, WSL, and IT admin maintenance guides. The work on Ubuntu with 
Active directory goes into the desktop space because the work is 
targeting Ubuntu desktop sessions with Active Directory; that is also 
why this cannot go in the server guide.

The developer guide would include things like guides on fixing bugs in 
Ubuntu debs, container overview and initial lxd setup for a developer 
environment geared at fixing Ubuntu bugs.. things like the Enterprise 
desktop team (Active Directory and WSL), core snaps (their )

I just cannot see an argument for having all of this in the existing 
desktop guide.

> When Jon let us know that he wants to contribute to the desktop guide, 
> and since the onboard documentation is severely outdated, I started a 
> thread on this list to help him get started:
> 
> https://lists.ubuntu.com/archives/ubuntu-doc/2022-March/020810.html
> 
> @Heather: I think it would be good if also you familiarized yourself a 
> bit more with how the desktop guide is dealt with behind the scenes. 
> That might make the conversation about different options easier. ;)

Forgive me but I did already read that.. I read everything posted in 
March. I did familiarize myself with help.ubuntu.com and checked out the 
bzr branch [0]. I saw how the ubuntu-help directory seems to be saved 
off in the various release directories. This ubuntu-help maps to what is 
in ubuntu-docs [1], which pulls from debian's gnome-user-docs, which 
pulls from upstream's  gnome-user-docs[2].

[0] https://code.launchpad.net/~ubuntu-core-doc/help.ubuntu.com
[1] 
https://git.launchpad.net/~ubuntu-core-doc/ubuntu/+source/ubuntu-docs/help.ubuntu.com
[2] https://gitlab.gnome.org/GNOME/gnome-user-docs

What was NOT clear was that while the desktop guide itself is not tied 
to the underlying community wiki of help.ubuntu.com, it is difficult to 
identify a better solution, regardless of the rest of the desktop 
documentation needs.

As someone on the desktop team, trying to identify the lacking desktop 
documentation and organize filling those gaps on whatever tool, I needed 
this conversation to see walled garden nature of the desktop guide and 
how it must stay that way. We just can't loose those translations, so 
thanks a million for pointing out that really important point! But there 
is also a real need for additional documentation, and I see it going on 
a new desktop discourse instance. Even if you don't want to help with 
putting content there, your veteran opinion on the structure and content 
is valuable and welcome.

I didn't know about the conversation you both had with Monica and 
Daniele, otherwise I would have asked them where we're at instead of 
coming here :) But I've looped them in here, so they can chime in too.

Cheers,
Heather