Bazaar Developer Guide (Proposed)

[Ian Clatworthy]

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.
>> >
>> >
>> Andrew,
>>
>> 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 
https://bugs.launchpad.net/bzr/+bug/97657.

Ian C.