bzr-doc team mailing list archive

[Patrick Regan <patrick.rubbs.regan@xxxxxxxxx>]

On 12/7/09, Ian Clatworthy <ian.clatworthy@xxxxxxxxxxxxx> wrote:
> Hi everyone,
>
> It was only 3 weeks ago that we started the bzr-doc team and already the
> impact has been huge. I had a look over the bugs tagged with 'doc' today
> and the number is down from 55 to 35. Simply awesome! It's also really
> exciting to see the Administrator's Guide taking shape.
>
That's pretty good. I guess I didn't realize we had done that much
work. NMB did a lot, and his Admin-guide is really good. I didn't know
how to do a lot of what is put in there, but I'm getting a good grasp
of it now. Well done.

> For those who have been sending in patches, have you found the
> experience a positive and rewarding one? Are there things we could do to
> improve it?
>
Patches have been going great for me. Everyone has shown patience when
things haven't gone perfectly and give good feedback. Merges were done
pretty quickly and people were willing to spend time to make sure I
got it right, even if telling me what I did wrong was more work than
fixing it themselves. This helps make it easier for me to get it right
the next time.

<snip>
> Looking forward, here are some of the things I'd like to see:
>
> 1. The glossary moved from the Wiki into our standard docs.
>    Several of the outstanding bugs basically ask for a certain terms
>    to be better explained. If we can get the glossary moved across,
>    we'll have a better place holding those definitions. We'll also be
>    able to add cross-references into the glossary from the rest of
>    the docs.
>
Great idea. A link to the wiki page might be nice. I found it, but it
took a while.

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

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.

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

> Does those things sound OK to everyone? If so, any volunteers to take
> these tasks on?

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. I'll work on adding some terms
today. Anyone is welcome to add and I'll merge them in.

I'd also like to hear what people think about a system's administrator
guide (not to bzr but to a system in general). Is that relevant, or
within the scope of this project? Should we create a doc for etckeeper
and then link to it?

Pat