Getting started with the desktop guide

[Gunnar Hjalmarsson]

On 2022-03-17 00:14, Jon Duncan wrote:
> After looking over everything, contributing to the Ubuntu Desktop
> Guide seems like it would be the best place for me to begin.

Ok, great. Then I ought to be able to help. Below you find an attempt at 
a roadmap for beginners.

> I'm sure that a lot must be done to prepare for 22.04 LTS!

Hmm.. Not much time left. 
<https://wiki.ubuntu.com/DocumentationStringFreeze> for 22.04 is at 
March 24, and to give the translators a fair chance to do their part, no 
changes should be made after that date.

So realistically I think we need to consider 22.04 a done deal. Possibly 
there is time for some tiny change, but I can't think of anything 
particular right now.

You also asked about areas that need attention. One thing is that the 
upstream pages actually refers to vanilla GNOME, while Ubuntu ships a 
GNOME desktop environment with some not insignificant modifications. 
Those modifications are currently undocumented, but I think it would be 
desirable to include some of them in the desktop guide. But to do that, 
we first need to figure out a way to do it which won't increase the 
maintenance burden significantly.

So I think Ubuntu 22.10 is a more realistic target for your first 
footprints in the desktop guide.


Now the "roadmap". Not sure how much you already know, but let me start 
with some things which are good to know to be able to work with the 
desktop guide.

It's written using the Mallard (<http://projectmallard.org/1.1>) markup 
language. The source pages are installed at

/usr/share/help/C/gnome-help

The equivalent translated pages are installed at

/usr/share/help/de/gnome-help

in case of German, etc.

When you click the "Help" button in the dock, you view the installed 
pages using GNOME's help browser yelp. The same content is published on 
the web, where the Mallard pages have been converted to HTML 
(<https://help.ubuntu.com/stable/ubuntu-help>).

We use two source packages: gnome-user-docs and ubuntu-docs. 
gnome-user-docs consists of upstream GNOME Help pages, while ubuntu-docs 
provides some supplementary Ubuntu specific pages.

git repos are used to manage the contents. The two most important repos are:

* for upstream:
https://gitlab.gnome.org/GNOME/gnome-user-docs/

* for ubuntu-docs:
https://code.launchpad.net/~ubuntu-core-doc/ubuntu/+source/ubuntu-docs/+git/ubuntu-docs/+ref/master

I would suggest that you clone those two git repos and look around to 
familiar yourself with the structure. (I'm assuming for now that you 
know how to do that. If you need pointers to get started with git, 
please let us know.)

There is also a gnome-user-docs repo here:

https://salsa.debian.org/gnome-team/gnome-user-docs

That's where the packaging of gnome-user-docs in Debian and Ubuntu is 
tracked. But that repo is of limited relevance for contributors of 
desktop guide contents, since we typically don't modify the upstream 
pages. When a need to change something in gnome-user-docs arises, we 
report it upstream and/or submit a merge proposal to the 
gitlab.gnome.org repo.


It's late, and I stop there for now. Probably you'll respond with a 
bunch of questions, and I'll try to answer those as best I can.

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