| Thread Previous • Date Previous • Date Next • Thread Next |
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.
-Neil
| Thread Previous • Date Previous • Date Next • Thread Next |
