Fwd: Server Guide HTML

[Matthew East]

Hi Adam,

On Wed, Aug 18, 2010 at 8:01 PM, Adam Sommer <asommer70 at gmail.com> wrote:
>> 2. We could take the serverguide out of the ubuntu-docs bzr branch /
>> source package, and put it in its own bzr branch which wouldn't be a
>> source package and which wouldn't have the same constraints. That
>> would raise some process issues about how the docteam would manage the
>> separate branch and translations of the guide, which is a conversation
>> I'm happy to have, but equally would be quite a big change so we
>> should discuss it carefully. Possible disadvantages might include
>> having to manage different processes for different documents; and
>> potential divergence of common files used (such as those in the "libs"
>> folder).
>
> I think it should be pretty easy to keep the libs directory synced between a
> serverguide branch and the main ubuntu-docs branch.  I imagine bzr merge
> will come in quite handy for this.  The process should work pretty easy
> between all common files.

Yes, bzr merge -r works fine for things like this, but we've found
with kubuntu-docs and xubuntu-docs branches that the common files
diverge pretty quickly, probably just because of a lack of people
taking care of things like this. The same might not be true of
serverguide given how well you've taken care of the document over the
past few cycles :)

> Seems like overall the process for contributing to the serverguide branch
> will be very similar to the ubuntu-docs branch as well.  We'll need to
> update the instructions in the wiki, but hopefully it won't be too
> complicated for new contributors.
> Another idea that comes to mind is potentially adding some type of shell
> script to the ubuntu-docs package that would create a local branch.

>From the docteam's point of view, one thing that is made more
cumbersome by separating documents into a separate package is the need
to get that different branch in order to commit a small fix, or to
build html to put on help.ubuntu.com. Currently, building
help.ubuntu.com is (with the exception of the installation-guide
document) all done from a single command in the root directory of the
bzr branch, but creating more branches would make that process
potentially more complex.

What I think we should investigate is an easy way for ubuntu-doc
contributors to grab documents which might be located in different bzr
branches around the place so that html can be built. It would be
awesome if we could establish some kind of "meta-branch" with the
ability to bring in branches of relevance to ubuntu-docs into one
place. I heard once of a "nesting" feature of bzr, so will investigate
whether this could do what we like. On another thread we're discussing
the possibility of docteam contributors becoming more involved in help
files which are shipped in packages outside ubuntu-docs, such as
software-center, and this sort of process would be useful to that too.

> I'm fuzzy on the translations aspect... what issues can you see with
> creating a separate serverguide branch?  I imagine that would require them
> to look into two different places for translations?

>From the translation point of view, it's a question of making sure
that the serverguide is discoverable for translators so that it gets
their attention in the same way that it does now. Launchpad provides
the ability to import/export translations from branches
semi-automatically, so the process itself shouldn't be problematic.
But given that the document wouldn't appear in the ubuntu-docs package
any more, the translations would have to take place in the "upstream"
area of Launchpad, rather than the "distro" area. That might be fine,
as long as it is well documented. I've added David Planella for his
thoughts (David, sorry to drop you into the middle of this thread, but
hopefully the context is reasonably clear from the quotes above).

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF