bzr-doc team mailing list archive

[Ian Clatworthy <ian.clatworthy@xxxxxxxxxxxxx>]

Neil Martinsen-Burrell wrote:
> On 2009-11-24 07:06 , Patrick Regan wrote:
>> That makes sense. Is their need to give screenshots from different
>> environments? I have access to Windows and Ubuntu, so I don't mind
>> doing some sort of mix.
> 
> For the Explorer Visual Tour, Ian first did a complete set of
> screenshots on Windows.  Algis and I were then easily able to recreate
> the screenshots under Linux and Mac OS X, respectively.  I would stick
> with this same model, and aim for consistency initially.

Yes, that approach proved more successful than I expected, thanks to our
great community. One side of me thinks a single document is better
because it's easier to maintain. But I also have this strong gut feel
that tells me users are passionate about their selected OS/desktop and
appreciate documentation that is customised for their desktop accordingly.

For tutorials, I think we should favour the Visual Tour approach:

1. The author should pick one platform.
2. We give ourselves a few days to polish grammar/spelling/clarity.
3. Then others duplicate it for each major desktop.

As Neil said, it really doesn't take long (except capturing the
screenshots). Tutorial content is pretty stable in my experience as well
so ongoing maintenance isn't a problem in practice.

For the eventual manual (called the Bazaar Explorer User Guide say), I
expect the content to be less stable as it will evolve as each new
feature gets added. A single document with a mix of screenshots from
different environments might be a better choice in that case.

Ian C.