bzr-doc team mailing list archive

[Ian Clatworthy <ian.clatworthy@xxxxxxxxxxxxx>]

Patrick Regan wrote:
> On 12/7/09, Ian Clatworthy <ian.clatworthy@xxxxxxxxxxxxx> wrote:

>> 2. More specialised tutorials. I'd like to see one oriented towards
>>    website maintainers say. I think Emma had some great ideas along
>>    these lines IIRC. Emma?
>>
> Another I've been thinking about was one for System's Administrators,
> but it might be better to write for the etckeeper project instead.
> What do people think?

Yes, one for system admins explaining how to VC config files would be
great. You could include some basic info re etckeeper there and, if
necessary, link out to a bigger doc on it.

> I also think that specfic tutorials on popular plugins might be good
> too. Right now the official docs have a user-reference type doc for
> each popular plugin, but there is very little use-case driven
> documentation. For example, how do you use bzr-pipeline rather than
> what commands are added.

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.

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?

>> 3. Break the User Reference into topics instead of one big doc.
>>    Many places in the User Guide (say) link into the User Reference
>>    so it would be good to get a better online structure for this
>>    document agreed to and bedded down soon (so we can fix any broken
>>    links well before 2.1 ships).
>>
> I think this is a great idea. It's really hard to navigate that page
> sometimes. The table of contents on the side is too big to find what
> you want.
> 
> I think that the "Concepts" section could stay one one page, but the
> "Lists" section needs to be broken down another level or two. It's
> really long. Also, I'm not sure why it's called "Lists." Can someone
> enlighten me?

Because I couldn't think of a better name. :-)

> 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.

Ian C.