Getting started with the desktop guide

[Gunnar Hjalmarsson]

On 2022-03-20 01:17, Jon Duncan wrote:
> I am less familiar with Mallard, but the documentation you linked is
> helpful. I have experience writing HTML, and the syntax and usage
> look similar to HTML and other markup languages I've worked with.
> 
> I was able to make local changes to several .page files and preview
> them using yelp, so I don't think I'll encounter many problems making
> changes to preexisting documents.
> 
> However, if it came to drafting an entirely new page, I would
> probably need some technical help, especially as it pertains to links
> and relationships to the rest of the documentation.

It's true, as Doug pointed out, that we haven't added new pages 
frequently. But if we are going to document some of Ubuntu's changes to 
GNOME, we'll probably conclude that some new pages will help.

When drafting new pages, I have usually started with copying a similar 
page and editing from there. That way I'm served with some basic Mallard 
syntax, and don't need to visit the Mallard documentation so often.

There is also a tool to validate the .page files for syntax, links, etc. 
As an example, if you are in the ubuntu-help/C directory in your local 
ubuntu-docs clone, you can run this command:

./validate.sh

> About documenting the modifications to GNOME in Ubuntu:
> 
> Do we already have a list of Ubuntu's modifications to GNOME?  If we
> don't, what do you think could be a good way that I could create such
> a list?  Would it be effective to run vanilla GNOME alongside Ubuntu
> Desktop, manually going through all the menus and settings, or can
> you think of a more effective method?

As far as I know (I may be wrong) there is no such list.

My idea of a first step is to ask the desktop team for input. Some of 
the desktop team members know about the significant modifications from 
memory. So why not post a new topic with our thoughts here:

https://discourse.ubuntu.com/c/desktop/8

and find out which modifications the team would like to see documented 
at first hand.

I'd like to add that several of the modifications are self-explanatory, 
so I don't think the lack of documentation (since Ubuntu 17.10) have 
caused a lot of user confusion. Nevertheless, providing a desktop guide 
which reflects what's actually shipped with Ubuntu gives a better 
impression.

> You also mentioned trying to figure out a way to document these
> changes without increasing the maintenance burden. I don't really
> have many ideas yet. I would first need to understand what options we
> have, and also understand how those options add to the burden. I'm
> guessing that we just don't want to add a bunch of pages to the
> Ubuntu-specific documentation if the differences are not that
> significant.

The latter is one of the things I had in mind when mentioning the 
maintenance concern.

Basically I see these options:

1. *Add* pages which explain the Ubuntu specific stuff. That's the 
easiest way from a maintenance POV.

2. Fork certain pages from gnome-user-docs, and ship modified variants 
with ubuntu-docs. By doing so we would create a need to manually watch 
changes to the gnome-user-docs contents, and update the forked page 
accordingly. It would also bring more strings to the translators, even 
if they have already translated most of the strings upstream. So from a 
workload/maintenance POV I think this option should be avoided and only 
used when absolutely necessary.

3. Propose conditional contents in the upstream pages. It's possible, 
for instance, to include strings in gnome-user-docs which will only be 
shown on Ubuntu but not on other distros with GNOME desktops. The latest 
example of that started with <https://launchpad.net/bugs/1954429> and 
resulted in this upstream commit:

https://gitlab.gnome.org/GNOME/gnome-user-docs/-/commit/323bdf23

> Maybe we should try to determine which modifications are sufficiently
> different that our documentation needs to reflect those changes?

Indeed we should. Documenting every tiny modification would be crazy.


If you want to get the ball rolling, I would suggest that you make a 
discourse post as I mentioned above. With the input we get there, we can 
then discuss what to include — and how — more specifically.

But maybe this initial discussion isn't finalized yet, and you prefer to 
get some more things clarified first. If so, please go ahead. :)

-- 
Cheers,

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