Bazaar Developer Guide (Proposed)

[Ian Clatworthy]

Eugene Wee wrote:
> Hi,
>
> I am actually working on a guide for novice users. Part of my 
> motivation is that my fellow university students are blissfully 
> unaware of the benefits of a version control system when they code. 
> (The other part is that I am at the end of a technical writing module, 
> and I figured that practice makes perfect :P )
>
> Like you, my experience as a user is still pretty fresh. My aim is to 
> make it more of a training manual that guides from scratch, with the 
> possibility of converting it into a CHM file for Windows users. Would 
> you be open to this possibility? I am not too sure how to retrofitit 
> for the wiki and at the same time keep updates for a CHM file.
>
> Regards,
> Eugene Wee
Eugene,

We had a long discussion on Bazaar doc today on #bzr on 
irc.freenode.net. One of the outcomes of that is that we'd like to use 
reStructuredText (reST) as the master format for as much doc as 
possible. See http://docutils.sourceforge.net/rst.html if you are able 
to assist. One of the sweet things about reST is that you can use it 
stand-alone and use it inside MoinMoin wikis. In the later case, simply 
put "#format rst" at the start of the doc and MoinMoin is smart enough 
to treat remaining markup on that page as reST.

reST can be converted to quite a few formats. I don't know of a CHM 
converter - I haven't looked for one - but I agree that help formats are 
legitimate target formats for Bazaar documentation. FWIW, when 
programming on Windows, I strongly favour the Windows help browser for 
getting around the Python documentation in place of the plain Web pages 
or PDFs. As well as the help format for Windows, the formats used by 
Gnome, KDE and OS-X would all be valuable when time and priorities permit.

In summary, it's great to hear you're using Bazaar and working on better 
doc for it. If we can maximise the amount of doc source in reST and 
progressively get the various converters in place, we can then get all 
doc into all formats, rather than various docs only available to some users.

Ian C.