Playbook One

[Dougie Richardson]

Hi Nathan,

2009/4/24 Nathan Handler <nhandler at ubuntu.com>:
> 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'.

I agree, I've changed it.

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

I'm not sure about this because the idea is that this is something
that a user would download from a page where our structure is
mentioned. With space at a premium I'd rather leave out details that
don't affect contributing directly - unless you feel there is a strong
need for this.

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

I've changed it to bzr diff.

Can you expand on the use of the --fixes flag as I haven't used it -
does it mark the bug as "Fix Commited" in Launchpad? If so then I'd be
keen not to use it as the person checking and pushing the patch should
be changing its status otherwise bugs will get missed.

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

Good idea, I've added it.

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

Thanks!

-- 
Regards,

Dougie Richardson
http://www.lynxworks.eu/
dougierichardson at ubuntu.com