Proposal: multiple binaries, one source package

[Jim Campbell]

Hi All,

2009/4/1 Cody A.W. Somerville <cody-somerville at ubuntu.com>

> Hello Team,
>
> The work I've been doing the last few days to get the Xubuntu documentation
> updated and Matthew's unhappiness with some of the changes I've made to the
> setup in Launchpad has gotten me thinking. The root reason why the Xubuntu
> docs now has its own project in launchpad is because Xubuntu has its own
> source package. Matthew has talked a lot about working together and I think
> thats awesome. So why don't we really take things to the next level and do
> something that will actually assist us in doing just that - multiple
> binaries, one source package.
>
> No, this has nothing to do with the similarly named and very disgusting
> video. Instead, it has to do with sharing! Sharing is good, right? Well lets
> share the same codebase. Lets have one source package that is used to build
> binaries containing the documentation for all the derivitives. This would
> allow us to share common material, a single shared build process, a single
> shared bzr branch, and a single project on launchpad. How to setup ones
> printer may be more than just slightly different in Ubuntu compared to
> Xubuntu but how to use pdigin to connect to MSN isn't. How to change the
> theme might be more than just slightly different in Kubuntu compared to
> Edubuntu but the basics of using the command line are the same. Lets reuse
> that common stuff!
>
> I've talked to Jim about this and he said he learnt some interesting stuff
> at a recent conference he attended in this area. I think this would be an
> interesting topic to pursue for Karmic. What do other folks think?
>
> Cheers,
>

Cody is right in that I learned a bit about this in the past week.  I
learned about architecting content for re-use in the context of DITA [0],
though, as DITA appears to be the "new black," of the technical side of User
Assistance development.  In other words, companies are developing a whole
bunch of proprietary tools to assist writers in creating DITA documents so
that the writers get the benefits of DITA without always having to touch the
code.  However, these companies are not doing the same kind of work for
docbook.  To me, the DITA Open Toolkit seems all well-and-good for what it
does, and it is Free software, but its benefits over docbook to our project
are debatable.  I saw some discussion about DITA on a gnome-doc ML back
around 2006, but any DITA / Docbook discussion is probably best-saved for a
separate thread.

Nonetheless, this "code-reuse" talk got me thinking about how we could reuse
code in the various flavors of Ubuntu, and whether it would be possible to
have one set of code produce multiple binaries.  Reusing code may be
particularly helpful now that we have more flavors of Ubuntu.  For example,
Dougie has talked about writing docs for Ubuntu desktop remix; that's yet
another flavor of Ubuntu that shares some significant similarities with
other flavors.  To me, this means it's another set of documentation that
requires regular updates with chances for divergence from the main Ubuntu
documentation.

Of course, I can see some advantages and disadvantages of combining the docs
into a single source:

Some advantages:
* Some aspects would become more simple: One main branch in launchpad,
making it easy to find the code for all flavors for people who want to
contribute.  Updates to common sections such as networking or command-line
info would be stored in one central spot.  One update benefits all related
documentation sets (this also applies to architectural changes).
* Translations. All of the documentation code for all of the flavors that
requires translation is in one package.  This could simplify things for the
translation teams.
* Greater shared sense of responsibility.  We really become one team.  A bug
filed against Kubuntu portion of the docs becomes more relevant to me, and I
have a better understanding of how Kubuntu works.  A bug filed against the
Xubuntu portion of the docs becomes more relevant to Jonathan and Richard,
and they get a better understanding of how Xubuntu works.  People would see
how great Xubuntu is, and they would cry.  Maybe.
* More eyes on the docs. This kind of ties in with some of the previous
points, but with less crying.  For better or worse, I know that there were
times that I noticed things in the Ubuntu docs that I just didn't fix
because I was so focused on the Xubuntu docs.  Or there was something that I
saw as a very minor typo, so I corrected in Xubuntu docs, but it didn't seem
important enough to go and change it in Ubuntu docs.  Perhaps the same
applied to people who saw something that could be fixed in Xubuntu docs, but
they didn't mention it because it was "Jim's Domain," or because they were
focused on their own documentation. Having more eyes on one set of docs
would encourage us to fix those kinds of things, or to at least point them
out more and recommend that they be fixed.

Some possible disadvantages
* We'd have to overhaul a lot of stuff.  It would require us to overhaul the
documentation codebase on a number of levels to accommodate the various
flavors using one package.  We'd have to sort out what items should be
combined, what items should be kept separate, and how to accommodate minor
differences between flavors when we do decide to combine the documentation.
Files, folders, and links may each need to be renamed.  We'd have to
establish file and folder naming conventions and new procedures.
* Linking. Ghelp links are great for Ubuntu, but they are not great for
Xubuntu.  Kubuntu uses their own KDE-based linking method (I think they call
their links "klinks")  :-P.  Could we accommodate the differences by making
all links entities?
* How to do it.  I know that it can done relatively easily through DITA
("DITA Maps" handle the larger aspect of what topics get included in what
final binaries, and "conrefs" handle the smaller aspects of flavor-based
differences within the documents themselves), but we don't use DITA.
Matthew probably has a better idea about whether accommodating this kind of
approach is possible and practical with docbook.
* Translations.  Although translations would be reduced in one respect due
to code being reused, there may be more overall content to translate.  What
would happen if a translation group translated 94% of the Ubuntu-specific
documentation, but only 70% of the documentation in the overall package?
* Additional complexity for new contributors.  It may take a bit longer for
new contributors to get up to speed on how we manage the docs.
* Where to draw the line. Do we include mythbuntu-docs or
ubuntu-studio-docs, too?  I'm not even sure if these teams have doc
packages.
* Building the packages would become a bit more complex.
* I'm sure there's other stuff I'm leaving out.  :(

I know this may be a lot to take in, and there may be flaws in my arguments
or reasonings, but please share what you all think about this.  Thanks very
much,

Jim

[0] http://dita.xml.org/wiki/the-dita-open-toolkit
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20090402/2fe3ea75/attachment.html>