Ubuntu desktop documentation scope and location

Thu May 5 17:43:22 UTC 2022

Hi Gunnar and friends,

After the busy end of release, then jetting off to Italy for some 
vacation and a conference, then coming out of the jetlag fog that has 
followed.. I'd like to pick this up with a refreshed sense of purpose 
towards the documentation :)

On 4/20/22 08:07, Gunnar Hjalmarsson wrote:
> 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.

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.

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

> 
> 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. Perhaps there's some way to integrate Mallard and 
Discourse, but I'm not aware of any.

Now, that being said, while Discourse is the way we've been told to go, 
I cannot get a green light to get a space setup for desktop discourse 
documentation. So as an engineer that is passionate about improving our 
documentation, I feel some frustration of needing to move along but not 
being allowed to. I have some pressure to publish some documentation 
targeting the enterprise folks Now, with no forever home for it.

So Conner was accurate in identifying the enterprise docs need as what 
spawned the need for a general docs discussion here.

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

Hey no worries, I appreciate your assistance. You're right, none of this 
is obvious to newcomers :)

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

Everything Ubuntu has a community aspect, and so it is my belief that 
the community has a stake in what we do and that makes your opinions and 
advice just as valid as a traditional Canonical employee :)

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

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?

Cheers,
Heather