Ubuntu desktop documentation scope and location

[Gunnar Hjalmarsson]

Hi Heather,

Sorry for the delay..

On 2022-04-08 20:15, Heather Ellsworth wrote:
> 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.

Ok, good. With that, together with Daniele's clarifications, I too think 
we are on the same wavelength.

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

Then I understand better.

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

Now I'm not sure I follow you.

Basically I think we should decide where translations is important and 
where it's dispensable. Enterprise admins and developers can be assumed 
to be able to understand written computing English, and hence discourse 
is a suitable tool for such docs.

As regards the user guide, the target audience includes 'user Joe' in 
non-English countries, which makes it highly desirable to provide 
translations. In my book that's true both for the existing content and 
for additional stuff.

Please note that the desktop guide already includes some Ubuntu specific 
stuff. Most importantly we have the "Install & remove software" section 
which does not exist in GNOME Help:

https://help.ubuntu.com/stable/ubuntu-help/addremove.html

Also, while also GNOME Help has a "Get more help" section, in Ubuntu's 
desktop guide we have filled that section with different contents:

https://help.ubuntu.com/stable/ubuntu-help/more-help.html

And we may extend it further to serve the needs of a reasonably complete 
user guide. My idea is that new things, like the ones you mentioned, 
should also be written using Mallard markup language and translated.

I can imagine that sometimes there may be an urgent need to inform the 
users about something. There may also be contents of a temporary nature 
where it wouldn't be worth it to let it pass the translators. But I'd 
like to see those as exceptions.

So to summarize my idea:

1. User guide: Mallard + translations (both existing and additional
     content)

2. Enterprise admins: Discourse

3. Developers: Discourse

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

My sincere apologies for implying otherwise. Maybe I understated the 
complexity. After all it's not obvious how things work and why.

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

I think the discussion is refreshing. And I think it's very positive 
that you as a Canonical desktop team member get involved. The desktop 
guide has been maintained by volunteers all since the start, AFAIK. I 
think a mix is more appropriate.

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

"Veteran".. Ha, ha. :)

But your assumption is probably correct. I won't have enough motivation 
to write content for enterprise admins and developers.

As for the user guide, my intention is to be around for a while longer. 
I'll keep helping to make it stay afloat, and hopefully provide guidance 
to Jon and other new contributors.

As regards the help.ubuntu.com domain, Doug and I have worked together 
with it for some years. Via a bzr branch with the same name we have 
upload access to the site.

-- 
Rgds,

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