Bazaar Developer Guide (Proposed)
ian.clatworthy at internode.on.net
Thu Apr 12 02:32:55 BST 2007
Jonathan Lange wrote:
> On 4/12/07, Ian Clatworthy <ian.clatworthy at internode.on.net> wrote:
>> Andrew Bennetts wrote:
>> > Ian Clatworthy wrote:
>> > [...]
>> >> the various Wiki pages covering related material into this. A
>> first cut
>> >> at a Table of Contents can be found here:
>> >> http://bazaar-vcs.org/IanClatworthy/ProposedBazaarDeveloperGuide.
>> > Having a "Using the Bazaar API" section would be valuable, but it
>> does not
>> > belong here. The audience for an API guide is broader than just
>> people working
>> > on bzr proper, as it includes plugin authors and other users of
>> bzrlib. I'd
>> > love to see it written, and linked from the Developer Guide
>> (whatever form it
>> > takes). The Bazaar Developer Guide is about project policy and
>> recommended ways
>> > to work with the bzr code; an API guide is much more broadly
>> applicable, so
>> > deserves better visibility than being buried inside this guide.
>> The idea was to make the Dev Guide a one stop shop for all developers,
>> including those people writing plug-ins and 3rd-party tools. The latter
>> groups don't need to follow everything we do w.r.t. policies but it
>> doesn't hurt for them to be aware of them.
> I think it would be better to have the API guide in a separate
> document. Many third-party developers would look at the first part of
> the table of contents there and quickly decide that the document is
> not for them.
Why do you think that? I would have thought that many of the topics -
exploring existing stuff, discussing ideas, API evolution, input &
output, error handling, etc - would be of high interest to developers
interfacing with Bazaar or extending it with plugins.
> Even though it doesn't hurt third-party devs to know about Bazaar's
> policies, it probably doesn't help much either.
I expect the policy centric topics to be clearly enough marked (in the
TOC) that they could avoid the ones they weren't interested in.
I guess I don't have a clear picture in my head just yet re what a
separate API Guide would look like and why it's more valuable *outside*
of the Developer Guide than in it. In my experience, the best Guides are
role-centric, e.g. User Guide, Developer Guide, Administrator Guide.
Down the track, there may well be a case for things to evolve - Core
Developer Guide, Plug-In Developer Guide, 3rd-Party Tool Developer Guide
- but I'd like to start with just one initially. Wikis are very good at
reusing much of the content - once it exists - in multiple spots, e.g.
separate TOCs for the more specific guides.
After getting my head around the why and how via a Guide, I'm usually
happy going straight to quality reference material, e.g. the stuff
generated by epydoc. I want to get that up on the Web as well - see
More information about the bazaar