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

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ian Clatworthy wrote:
> Aaron Bentley wrote:
>> I don't think that's discoverable at all.  If we have a doc directory,
>> people will look there for documentation.  If they can't find what
>> they're looking for there, many will assume that the documentation they
>> are looking for does not exist.
> 
> Hmm. Sorry to be a pain about this but I'm not sure I understand:
> 
> * Users will find the doc they'll looking for from the doc/index.html
>   page, including a more extensive "User Reference" than we've
>   ever published before

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.

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

>, and developers looking in the
> wrong place. The latter ought to know about our help topics being
> largely provided by code and if they don't, we can easily redirect them.

I'm not so worried about developers.

> If I add a readme.txt to doc/en/user-reference explaining that the
> content of that document comes from bzrlib/help_topics, will that ease
> your concern?

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.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHXqTB0F+nu1YWqI0RAuqdAJ0VIMw//OSCUFJHxhnqphCaLN71SQCffA4C
dnDSBBfhlKG5y/3e5OFtCX8=
=snq7
-----END PGP SIGNATURE-----