Ubuntu desktop documentation scope and location

[Doug Smythies]

On Wed, Apr 6, 2022 at 2:31 PM Heather Ellsworth
<heather.ellsworth at canonical.com> wrote:
>
>
> Hello Folks,

Hi,

And thank you for your email and interest.

> I'd like to contribute to these lovely docs, so first let me say an
> overdue hello! The work done to maintain ubuntu-help has been so
> valuable and I'm happy to work with you all :)
>
> I work on the Ubuntu desktop team and have had the chance to recently
> dive into the documentation of the integration of Ubuntu and Active
> Directory. I worked with the Enterprise Desktop team to update a
> whitepaper (that is over 60 pages), on everything related to setting up
> and managing Ubuntu servers from an Active Directory instance. Now we'd
> like to copy/pasta that information (with formatting) to some public
> space. This naturally led to an existential crisis about documentation
> and goals and such :)

Did you consider to review and update the Ubuntu Serverguide
sections on active directory?

The Ubuntu Serverguide moved from docbook to discourse as
of 20.04. On the surface that seems to me to be the place to
expend your efforts.

> I have been involved in some discussions on the desktop docs and have
> some thoughts on it's general goals, and how we can best use the tools
> to align with those goals. I also really wanted to take the Ubuntu
> Community's temperature on these subjects, so please feel free to
> provide feedback :)
>
> ## Audience
> There are 3 types of audiences that I believe Ubuntu desktop
> documentation should aim to enable:
>    1. community user docs: I believe this is help.ubuntu.com. This is
> the foundational knowledge all Ubuntu users need.
>    2. developers docs: for those developing on/for ubuntu. This would
> include guides on debian packaging, deb package process/maint, launchpad
> bug fixing, container setup, etc. There is not much overlap between
> developer docs and community user docs. I see the developer docs each
> pointing to the more foundational knowledge found on the user docs where
> needed. There is no existing page for this.
>    3. corporate users/IT/Enterprise support for Ubuntu desktop. These
> folks want guides on provisioning lots of machines, Active Directory
> integration, rolling out updates at scale. These docs will rely heavily
> on the foundational knowledge in the community user docs. These docs
> will likely overlap with field engineering docs as well, need to work
> out where the ownership lies. There is no existing page for this
> explicitly, but the Ubuntu Server Guide is heavily relied on.

Yes, the Serverguide is where I would expect to find information
on active directory.

> ## Tooling
> I've been told that we are going to use discourse as our documentation
> infrastructure.

That is news to me. Pretty much the entire desktop content is
merely copied from the upstream Mallard code.

> I don't have a deadline, but it seems like any major
> changes are strongly encouraged to be made in the discourse direction.
> This seems to be a fact, regardless of many opposing opinions. My point
> in bringing it up here is to not launch any sort of flame war, but to
> assume this and just move on.

Have you been in communications with Monica Ayhens Madon and
Daniele Procida, both from Canonical, and both were looking
into docs stuff some months ago.

Gunnar and I had a zoom meeting with them on November 30th,
but haven't heard from them since.

> So this leads to some big questions:
> 1. Does there happen to be an existing plan to migrate help.ubuntu.com
> to a discourse site?

For the Desktop help, no.
For the Serverguide, it already moved to discourse.
The installation guide will no longer be published.

> As far as I can tell, there is no
> https://desktop.io/docs (it would match the discourse naming convention
> Canonical is using for many other products found at docs.ubuntu.com).
> 2. When I still need to make a page NOW! (to have it for the release),
> because we don't have a permanent solution (discourse) setup, I'm told
> to put it on the wiki. But important product pages [0] should not look
> like they are from 2004. So is there another place?

You are too late for 22.04 initial release. The string freeze date has
already passed. The translators have things now.

I am not aware of another place, but again suggest the
serverguide. It no longer gets translated and never has any freeze
dates.

> ## Content
> help.ubuntu.com is great, but it would be nice if the screenshots were
> based in Ubuntu rather than GNOME OS. I don't see an easy fix that isn't
> extremely manual and a huge maintenance burden.

Correct.

>Has this been discussed
> before and thoughts on a fix?

No, and for  the above reason.
With the older desktop GUI (I forget the name) screen shot updates
were a maintenance burden, and there were not that many that
had to be changed for every release. I did them for some years.

>
> I like the idea of having user and developer documentation separate,
> similar to https://developer.apple.com/ and
> https://developer.microsoft.com/ and https://developers.google.com/
>
> I'd like to see perhaps one beautiful page (ubuntu.com) and easily find
> the documentation. Maybe that's a Docs tab with 3 options under it:
> user, developer, enterprise. Each one of these should take the reader to
> the right place, all backed in the same discourse so we have an easier
> time cross referencing pages.
>
> I have a whole google doc filled with suggested tutorials and how-to
> guides for each of the 3 audiences, if you'd like to see them. Just
> trying to not go too far in the weeds :)
>
> ## Communication
> Do you all have frequent meetings?

No. We used to, but nobody came.

> If so, what are the details?

There used to be a banner on the docs wiki pages each month
with details.

> If not,
> is anyone willing to get together virtually on a fortnightly basis or
> something similar?

Others might reply, I am less involved now that the serverguide
has moved to discourse. I only help Gunnar with publishing
updates to help.ubuntu.com as required now.

>
> ## Current needs
> The thing that launched me on this quest to begin with.. I need to make
> a public page of a lot of content - over 60 pages, currently in a google
> doc - that details Ubuntu integration with Active Directory. I could
> open a PR to add this to somewhere on help.ubuntu.com but, as I stated,
> I don't believe this is the right place. Does anyone have any suggestions?
>
> I really appreciate everyone's time and thoughts.
>
> Cheers,
> Heather
>
>
> [0] Me personally, I'm concerned with the documentation of the Ubuntu
> desktop team products: the GNOME-based Ubuntu itself and its apps, WSL,
> Active Directory integration, Flutter things like the new installer and
> software center. However, the statement stands. No important product
> page should look old.
>
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc

... Doug