[MERGE] [1.0] Move material out of User Guide into User Reference

Ian Clatworthy ian.clatworthy at internode.on.net
Tue Dec 11 23:43:18 GMT 2007


Aaron Bentley wrote:

> That's certainly not the primary way I use the documentation.  I read
> the plaintext.
> 
>> * "bzr help topics" will display the information in their console if
>>   they don't care to switch to a web browser
> 
> This won't allow them to read it in their viewer of choice.

Viewer yes, editor sometimes. There's always "bzr topic | vim -" for
example.

>> So the only people who won't find the doc are users looking for raw text
>> because HTML or 'bzr help' isn't for them
> 
> I think that will be a large proportion of our target audience.  Bazaar
> is a commandline app, so its users will tend to expect plaintext
> documentation.
[snip]
> That would improve matters, but not making this change at all would be
> even better.  Bazaar isn't a gui app, so we shouldn't be treating
> console-oriented users as second-class citizens.

I disagree. In no way does this patch treat console users as second
class citizens. It *adds* topics into 'bzr help' they never had before
and gives them a more extensive bzr_man.txt to search through in their
favorite editor.

If you think delivering plaintext doc in smaller pieces matters, I can
generate files for each of the help topics individually in additional to
the one big bzr_man.txt. I'm OK with that. But I honestly feel it is far
lower priority than providing a single, comprehensive User Reference in
HTML - something anyone with a web browser can search through and print.

Please reconsider the merits of this patch and consider our wider
audience. Suggesting not having it because 4 text files have been moved
into a different location, a location explained in a readme.txt for
anyone looking in the wrong place, is badly missing the point IMO.

Ian C.



More information about the bazaar mailing list