Playbook One

[Nathan Handler]

On Fri, Apr 24, 2009 at 9:06 PM, Dougie Richardson
<dougierichardson at ubuntu.com> wrote:
> I've done one so far and ask for as much feedback as possible
> obviously with a view to getting this out for Tuesday's Docs Day.

I think this is a very nice playbook. Here are a few of the suggestions I have:

1) Have them run all commands from the root of the bzr branch. For
example, in the "Check it..." section. have them run
'./scripts/validate.sh internet/C/internet.xml'.

2) If this document is meant to be an introduction to someone who
wants to learn about working with documentation in Ubuntu, you should
at least briefly explain the core-doc team (although this will most
likely need to be updated in the near future).

3) In the "Patch it..." section, you only demonstrate how to create a
bundle. I understand that this is one of the ways that users are
recommended to contribute patches. However, from my experience, it is
much easier to get a 'bzr diff' sponsored than a bundle. Another
method is creating a separate bzr branch and then requesting that it
be merged into the main branch. I have had a much easier time getting
patches sponsored when I follow one of these two approaches than with
the bundle. As another note, users should be encouraged to use the
--fixes flag when running bzr commit. This will allow them to clearly
show that that commit resolves a certain bug on Launchpad.

4) I would add an 'Additional Information' section at the end. This
section should provide links to various websites that the user could
visit in order to learn more about the doc team, working with
documentation, docbook, or any other relevant topic. If you are tight
on space, you could simple link them to an Additional Information wiki
page (since they will need to be at their computer anyway to take
advantage of this section).

These are just a few things that I noticed while reading through it.
However, I think this is a great document, and I will definitely be
printing out a copy to add to my reference sheet collection.

Nathan