← Back to team overview

bzr-doc team mailing list archive

Re: Off to a flying start


On 2009-12-08 16:48 , Ian Clatworthy wrote:
I'm working on a new Plugins Guide this week. The intention is that each
plugin will have sections for:

1. overview (as now)
2. special topics (new)
3. commands (as now)

So simply registering help topics within each plugin (e.g.
pipeline-tutorial) will result in those topics becoming part of the
plugin's page within the overall Plugins Guide.

For those of us who are plugin authors, can you let us know how we can make our documentation fit into your framework?

I'm also thinking of adding an "overview" topic for each category. It
would briefly introduce the plugins in a given category and provide some
advice on when to select given ones for different tasks. For example,
for Patch Management, there would be a topic called "Patch management
overview" and it would suggest stuff like:

* to break a large feature into pieces, use pipeline
* to manage local changes over an upstream, use loom
* use rebase for interacting with an upstream in a foreign VCS

For the new "Metaprojects" category, it would give tips on when
externals vs scmproj vs builder is appropriate. And so on.

Does that sound ok?

I think that sort of information is very important. In writing the System Administrator's Guide and channeling my own experience as a system administrator, every time I present choices, I try to answer the question "How do I decide between them?"

I went ahead and created a branch for the glossary at
"~patrick-regan/bzr/glossary". As of the time of this writing, all I
did was add a glossary directory.

Cool. Looking forward to seeing the initial results. To begin with, I'd
suggest keeping the scope really small - 10 terms say - and ensuring we
get the structure right. Once that patch has landed, we can easily add
many more terms. Neil's System Administrator's Guide is following this
"structure + follow-on patches" path as well fwiw.

Note that this path is harder to take if you don't know that it's the path to take at the outset :) I just wrote a bunch of stuff and committed as I went. Then when I wanted to break it into small, reviewable, logical chunks, I had to start with a clean branch, cherrypick the structure changes, resolve the conflicts and commit. Then, I based seven one-revision branches off of that one for each topic and I pushed each of those to Launchpad for review.


Follow ups