up -- let's do more docs

Martin Pool mbp at
Thu Aug 24 07:58:46 BST 2006

I've put html documentation for Bazaar up onto  This
site will publish the current development documents as well as those
corresponding to each previous release.  These will be regenerated on
each new release and as changes are checked into head.  (It's only
semi-automatic at the moment because of the security setup of that
machine.)  I'd like to thank Alexander and John for doing the stylesheet
and generation code underlying this.

We still have much to do to make sure the documentation covers
everything, and that it's organized in a good way.

I'm really impressed by the fact that almost all code changes are now
accompanied by tests, (Much credit is due to Robert's leadership on this
by giving good review comments, helping people work out how to test, and
providing good mechanisms - and of course to everyone who writes tests.)  

I wonder if it could be possible to do something similar to make sure
code changes keep the documentation up to date?

I know writing docs is not everyone's favourite activity, and not
everyone is very comfortable in English.  But I think anyone can realize
when a code change ought to require a documentation change, and as a
team we can work out the right phrasing.  I really think even a terse
note is better than nothing, and can remind us to fix it later.  

So I'd like to suggest adding one more thing to consider in code
reviews: Should the change update the user manual, and if so does it?

At the moment the docs from the source tree are shown as part of the
wiki.  It's very nice that they look integrated like this, but I don't
think it's really the best place for them:

 - They won't be in sync with any particular version of the code,
   and so are likely to mention features that aren't released yet

 - If people change them on the wiki those changes need to be manually
   integrated; it's possible but may not happen

The advantage is that people can just get in and change them,
wiki-style.  That has happened on that page, but I suspect that if we
have a prominent "please send questions or corrections to" then it may
still happen.

So I propose to change those pages into redirections to the generated
static pages.


More information about the bazaar mailing list