Ubuntu desktop documentation scope and location

Fri May 13 01:13:58 UTC 2022

Hi again, Heather!

On 2022-05-05 19:43, Heather Ellsworth wrote:
> On 4/20/22 08:07, Gunnar Hjalmarsson wrote:
>> On 2022-04-08 20:15, Heather Ellsworth wrote:
>>> 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.
> 
> You are correct. Translations are a key that are compromised by
> publishing documentation on discourse, or outside of the Mallard docs
> that are packaged as the help guide.
> 
> I would say that we absolutely need the translations of the packaged
> offline help docs. And I agree that we could expect developers and
> enterprise folks to be expected to rely on English documentation. The
> server guide is only in English, and a perfect example of the
> expectations we can set on such an audience.

Agreed.

>> 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.
> 
> I think it would be great if we had translations for additional
> documentation, outside of the help docs, but I don't see a way to
> practically provide this.

With "additional stuff" I meant additions to the desktop guide. 
Actually, while we are having this somewhat high level discussion, I'm 
mentoring Jon Duncan who has started to write an addition to the desktop 
guide about the differences compared to 'vanilla GNOME'. We use the 
Mallard markup, of course, and it will later be passed to the 
translators just as the rest of the desktop guide.

So it's indeed practicable. :)

You also mentioned info on core snaps. Not sure what exactly you think 
of there, but it sounds as if that topic would fit in the current 
"Install & remove software" section in the desktop guide. (That section 
already mentions snaps, but merely as a packaging format as opposed to 
debs.)

>> 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
> 
> Thanks for pointing out some differences in our packaged help docs vs
> what GNOME has.
> 
>> 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.
> 
> We could, but this  seems to not fit with the discourse agenda being
> pushed on us.

Wait now, *who* is pushing that on us? It's not Daniele, judging by his 
message in this thread. He did mention Discourse as a likely replacement 
for MoinMoin which is currently used for the two wikis. But that's 
another thing. TBH, you are the only person I have heard talking about a 
"discourse agenda being pushed on us" in the context of official desktop 
documentation.

As a volunteer contributor to Ubuntu I expect maximum transparency. I do 
listen to arguments — once in a while I may even be convinced and change 
my mind ;) — but I hate being told that an anonymous body has made a 
decision just like that and without accompanying good arguments.

I wonder if we possibly talk past each other. I noticed in your reply to 
Doug that you argued for Active Directory being a desktop thing rather 
than a server one. And if it's that topic you have in mind, I can 
understand why you don't think it fits well in the desktop guide. I 
don't think it would fit there either.

But is there really a reason to decide if Active Directory fits best 
under desktop or server? Isn't that a topic which should better be a 
stand-alone set of docs? And those docs would reasonably not need to be 
translated; hence => Discourse.

>> 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.
> 
> Ok I know it's not ideal, but given my limitation on getting a
> desktop discourse space and the need for enterprise docs to be
> published asap, I would like to have a help.ubuntu.com/desktop page
> that would have a subpage for enterprise. That enterprise subpage
> would contain everything in that AD whitepaper plus more tutorials
> and how-to guides and such.
> 
> I was planning to write this all in markdown, to ease the transition
> to discourse in the future (assuming it IS coming).
> 
> This would be similar to help.u.c/rst but so much larger. The sheer
> scope of the necessary enterprise docs means I need a place for it to
> go now and grow.
> 
> Gunnar, Doug, Daniele: What are your thoughts on this?

Personally I share Doug's hesitation. But maybe it would be easier to 
comment on it if I knew who that anonymous body, who prevents you from 
using Discourse right now, is and which the arguments for holding you 
back are.

What Doug or I could do is uploading static HTML documents. There is no 
content management system at help.ubuntu.com which would allow any other 
format, so you would need to convert it to HTML somehow. Would it be 
worth that extra effort for a short time?

I did mention help.ubuntu.com/rst as an example, but I also want to 
remind of my reply to Daniele about the background to that page:

https://lists.ubuntu.com/archives/ubuntu-doc/2022-April/020844.html

Note that the page originates from a Discourse page...

-- 
Cheers,

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