Ubuntu desktop documentation scope and location

[Gunnar Hjalmarsson]

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.

> 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.

>> 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.

> 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.)

>> 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.


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. ;)

-- 
Rgds,

Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj