Proposed road map for ubuntu-docs

[Gunnar Hjalmarsson]

On 2017-04-29 04:27, Jeremy Bicha wrote:
> ... this is my initial thinking (or proposal I guess):
>
> 1. Ubuntu would ship gnome-user-docs
> 2. Ubuntu could also provide an ubuntu-docs package that injects
> pages into the existing gnome-user-docs framework. The Mallard format
> is designed to allow extra content to be added like this (it's how
> gnome-getting-started-docs works).
> 3. If we have to make changes to pages instead of adding new pages,
> we could just modify the debian/rules for gnome-user-docs to not
> install those specific pages. Then we just fork the page in
> ubuntu-docs. We could do the same thing if we wanted to replace some
> of the pictures.
>
> I think there are some benefits to not using patches for #3.
> - Ubuntu and GNOME could share the same translations for
> gnome-user-docs
> - I think it would be easier for the Docs team to work on regular
> help pages rather than having to deal with modifying distro patches.

Yes! This sounds clearly better than what I proposed. Most importantly 
we wouldn't need to struggle with the upstream translations, and it 
would also be more straightforward to upgrade gnome-user-docs.

One disadvantage with having two branches/packages is that we won't be 
able to use yelp-check before committing to ubuntu-docs to identify 
broken internal links, orphans etc. OTOH, the reduced number of pages to 
pay attention to will probably make this manageable. (And it will be 
possible to run yelp-check without this limitation afterwards, i.e. when 
both packages have been installed.)

One thing which remains to be dealt with is how to build the HTML for 
help.ubuntu.com. The .page files will be split into three source 
packages/branches:
- gnome-user-docs
- gnome-getting-started-docs
- ubuntu-docs

We need a convenient method to do that. Maybe a separate tiny branch 
with script + template which bases the build on the installed stuff in 
/usr/share/help/<lang>/gnome-help ?

In any case, I like your proposal, Jeremy. Thanks!

> One more optional idea:
> What do you think about converting the ubuntu-docs from bzr to git?
> Since the Ubuntu Docs team should be submitting many changes to
> GNOME directly now, I am thinking it would be easier for new
> contributors to only need to learn one version control system instead
> of two. Would switching to git be a problem for the existing team?

Well, speaking for me it would be a learning curve. ;) But it sounds as 
the right thing to do for the reason you mention.

However, it's probably not the most urgent step to take at the moment, 
and personally I'd prefer that we wait with it until the new structure 
is in place.

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