[MERGE] [1.0] Move material out of User Guide into User Reference
Aaron Bentley
aaron.bentley at utoronto.ca
Tue Dec 11 14:54:57 GMT 2007
-----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-----
More information about the bazaar
mailing list