mdke at ubuntu.com
Tue Mar 17 21:54:07 UTC 2009
On Tue, Mar 17, 2009 at 3:55 PM, Dougie Richardson
<dougierichardson at ubuntu.com> wrote:
> 2009/3/17 Matthew East <mdke at ubuntu.com>:
>> I don't agree. Our toolchain is not currenty cut out to produce
>> documentation that can easily be put into a drupal database, and
>> constructing such a toolchain would be a huge amount of work for very
>> little benefit as far as I can see. I think using a CMS is a very
>> large tool for a very small problem, if indeed there is a problem at
> Our current toolchain utilises XML, its not a _huge_ leap to export
> that to Drupal. I also don't think its that big a tool but it's
> certainly scalable if the requirement is there for it - say we want to
> give users the option to print PDF from out HUC site on the fly for
> example or for users to build there own set of relevant pages.
> There are other disadvantages to a set of statically produced pages,
> searching for example - tags and categories allow more accurate
> results based on the area you're interested in. For example if I
> search for "package" that's mentioned in nearly every page but if I
> qualify it with the "Install" category I only hit those pages. Now you
> could argue that "install package" does the same but it doesn't - it
> often refers to another page.
I think this underestimates the difficulties involved, and
overestimates the benefits.
On the difficulties, I don't believe that it is as easy as you say to
export our xml into a drupal database. I haven't worked with drupal
much but I'm pretty sure it's at least a serious job to make this
work. We'll run into issues with cross referencing too. A PDF with
broken links to other documents which are not in the PDF will look
rather unprofessional. That's the reason we don't build PDFs from our
xml, even though there is a perfectly good toolchain for XML->PDF.
On the benefits, I think the google search is currently working very
well. My only other exposure to drupal is the main Ubuntu website,
where the search is a lot worse. I think the PDF point is not really
an option regardless of the system we use - the difficulty in making
PDFs arises from the semi-modular structure of our documentation, not
the format or method of publication.
If there is interest on working to improve our website toolchain, I
think I'd much rather such efforts go into exporting our documents to
Moin wiki markup and automatically push them to a Moin wiki, so that
we could merge the static and wiki areas of the website and reduce the
confusing distinction between the official and community areas of the
site. At least with that there are some decent tools already available
which don't quite work but which could be built on.
Having two CMSes instead of one wouldn't really introduce any benefits
as far as I can see.
>> Conceivably we could make it possible for more people to commit to
>> that branch, but since I've always been the person building the
>> documents and am familiar with the various scripts used, it's just me
>> doing it at the moment.
> Isn't that a good reason to consider a system that avoids scripts and
> syncs with a launchpad BZR branch? Cron beats by hand any day (as long
> as it works of course!).
I don't understand this point, in particular this last sentence, but
FWIW the bzr branch is pulled to the server automatically via a cron
>> As for the suggestion that we could fix bugs on the website that
>> aren't fixed in the packages we ship, I think that's a dangerous road
>> to go down - once you do that you need to keep track carefully of what
>> has been fixed in which place, and the documentation may start to
>> diverge or be inconsistent. I think that if a bug is serious enough to
>> warrant a fix being pushed to the website, it's serious enough to
>> warrant the package being fixed as well.
> I don't think that it necessitates divergence and that's not what I
> meant. If the branches are linked to a CMS then changes to the web
> site are just the latest revision of what is in the current trunk.
That's fine - I was responding in this quotation to something Adam
said, not your email.
gnupg pub 1024D/0E6B06FF
More information about the ubuntu-doc