Proposal: multiple binaries, one source package

[Jim Campbell]

Hi All,

On Thu, Apr 2, 2009 at 6:31 AM, Matthew East <matthew.east at gmail.com> wrote:

>
> 3. For that reason, it's important that we go back and look at the
> reasons that we moved to separate branches in the first place. I've
> managed to find these two emails (and follow up responses), although I
> think there were probably others as well:
>
>  https://lists.ubuntu.com/archives/ubuntu-doc/2007-August/009160.html
>
>  https://lists.ubuntu.com/archives/ubuntu-doc/2007-September/009383.html

Based on those notes, and giving things more thought, here are a
couple of other ideas.

How would people feel about keeping document structures as they are
now (each flavor has its own, complete branch), but identify in the
wiki which components are shared between which versions?  Then, during
earlier parts of the documentation cycle, all doc-team members
(regardless of the particular flavor they usually contribute to) would
work primarily on the shared documentation (e.g., basic-commands,
advanced-topics, add-applications, administrative, etc.) in the
official Ubuntu branch repository.

As the cycle draws to a close, documentation team members who
primarily work on other another flavor of Ubuntu could extract the
common documentation topics from the Ubuntu docs, and apply them to
their flavor's branches.  For example, I would copy out the "internet"
section from Ubuntu and apply it to Xubuntu.  From there, it would
only require a few tweaks to suit Xubuntu.  (I think that this
approach might not benefit Kubuntu quite as much, as their docs are
oftentimes quite different.)

I think this would be better than doing a lot of merges to stay up to
date.  The above approach would allow people to spend more of their
time focusing on their flavor-specific elements in their own
repository, and bring over the close-to-complete documents from Ubuntu
toward the very end of the cycle.  They would then just have to modify
a little content and (perhaps - see below...) the linking structures
to suit their flavor (i.e., remove all of the ghelp links and replace
them with xrefs, ulinks, or kde-style links).

> 4. The main advantages of separate branches are that they are quicker
> to check out,

Agreed.  I didn't really think of the bzr speed issue.  Bzr has gotten
a bit better, but it's still not lightning-fast with larger branches.

and that contributors (whether documenters or
> translators) can contribute without necessarily being 100% familiar
> with all the relevant desktops. I would envisage serious confusion for
> translations in particular if we are publishing a common template for
> material which covers different desktops, because translators will not
> necessarily be familiar with how different desktops behave, and in
> some cases it may not be clear to which flavour a particular string
> belongs.

That's a good point, too.

>
> 5. If we do try to have the documents in a single source package,
> there are two ways to do this. One is to have the documents for each
> flavour in a separate sub-directory (which is how we used to do it).
> That would not really give rise to any benefits over the current
> system because the material would not actually be reused. The other
> way is to try and build documentation for different flavours out of
> single xml source files. This is technically possible using xml, but
> would require a hell of a lot of work. It would mean that each section
> of documentation would have to be "tagged" as applicable to particular
> flavours, and that the structure of the documentation and sections
> would have to be the same for all flavours.

That's right.

Contributors changing a
> particular string would have to work out whether that string was
> applicable to more than one flavour, or just one, and act accordingly.
> I think that would cause serious confusion, and it would also
> constrain us to a single structure of documents for all the flavours,
> which might not be practicable.

Right.  The person who I saw speak on this at the conference did
comment about how architecting content for reuse in this way affects
(and in some ways, constricts) how you are able to phrase things.

As Jim pointed out, linking would also
> be a major challenge.
>

Changing our approach to linking may be helpful, I think.  What if we
used entities to handle all of our links? If we store all of our links
in entities we could reduce the amount of time that we spend typing
links, reduce the opportunities for incorrectly-formatted links in the
documentation, and make it easier to update the links of URL's that no
longer work due to changes on the internet (if we update the link from
the entity once, and all applicable links would be updated).

This could also make it a lot easier to accommodate links across
flavors.  It wouldn't matter that Ubuntu uses ghelp links and Xubuntu
doesn't... we would just have to use different entity files, and note
that a different entity file is being used in the top-portions of our
xml pages.

I know that yelp uses the actual xml files - would using entities
instead of the actual ghelp links break things in yelp at all?

> 6. One of the main reasons for moving to bzr was the strong merging
> functionality that it has which permits us to merge material from one
> branch to another. So if someone working on xubuntu docs spots a
> change to an ubuntu document which is also applicable to xubuntu, it
> should be easy to use bzr's merging functionality to merge that.

Merging is easy but sometimes the changes can come in
fast-and-furious, so it can be hard to keep up sometimes.  Also, even
though merging is quite easy when there are no conflicts, it can eat
up time when having to resolve conflicts, especially where it is not
immediately clear where there are differences.  This isn't a huge
issue, it's just time that could be better spent documenting other
stuff (or eating or sleeping, etc.)

> Equally, the libs and other common directories can be kept in sync in
> the same way.
>
> On that basis I'm in favour of keeping things the way they are now.
> However, it certainly doesn't hurt to talk about improvements that
> could be made.

If people have other ideas, feel free to share.  Thanks,

Jim