Getting started with the desktop guide

[Jon Duncan]

Thanks Gunnar,

This info is very helpful.  

I cloned both repos and poked around as you suggested.

I have some working knowledge with git even though I have not used it very much in practice. I understand how a typical project is usually organized on git, and I know basic commands like how to clone, push, pull, commit, etc.

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.

----

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?

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.  Maybe we should try to determine which modifications are sufficiently different that our documentation needs to reflect those changes?

Looking forward to hearing your thoughts,

Jon


Mar 17, 2022, 15:52 by gunnarhj at ubuntu.com:

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