Ubuntu desktop documentation scope and location

Fri May 13 18:15:16 UTC 2022

Hi Gunnar :)

On 5/12/22 19:13, Gunnar Hjalmarsson wrote:
> 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. 

And I think there is a point to highlight here. I see the "Ubuntu 
desktop documentation" as being the desktop guide + the Ubuntu desktop 
enterprise docs + anything else that might come up that doesn't fit in 
one of those (or similar) existing places.

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

I have been watching that effort and think it's great :)

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

In hindsight, I think you're right. I think adding any info on an 
existing core application that becomes a snap would go in the "Install & 
remove software section".

> 
>>> 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 was wrong and the decision to use discourse for new documentation has 
not been made yet. While it seems likely, it hasn't been decided yet.

Regarding the desktop guide, there are and have been no plans or 
discussions about changes to the Ubuntu desktop guide processes or 
tools. No changes will ever be made to it without consultation. This 
group will be the first to be asked for your thoughts. We will (at some 
point but we can’t say when) start a project to deal with our wikis. You 
will be the first to be asked for your thoughts on that subject too.

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

I was wrong, I am sorry. Discourse has not been the decided platform 
yet. Since there is no ETA on a decision of future platform, we will use 
help.ubuntu.com.

> 
> 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 will just write static HTML, heavily linking to the existing adsys 
documentation.

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

I'm going to work with the Enterprise team in the next week to come up 
with an outline that meets their needs, and then start writing html and 
create direct PRs to the help wiki.

I hope this clears up my error of thinking discourse was the decreed 
solution, and my future intention. The help wiki will grow a bit to 
accommodate current needs, and when the wikis are tackled the community 
here will be the first to hear bout it, your input will be asked, you'll 
be involved in whatever is done.

Cheers,
Heather