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

Ian Clatworthy ian.clatworthy at internode.on.net
Tue Dec 11 13:28:07 GMT 2007


Aaron Bentley wrote:
> Ian Clatworthy wrote:
>> The files are now in bzrlib/help_topics/en. I think that makes them
>> discoverable enough. (All help topics are either in
>> bzrlib/help_topics.py or bzrlib/help_topics/ - basically right next to
>> each other.)
> 
> 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

* "bzr help topics" will display the information in their console if
  they don't care to switch to a web browser

* bar the title, the User Reference is fully generated from these
  same help topics, the content of which all comes from probing
  internal registries or from bzrlib/help_topics/* (well it will
  when I implement Alex's requested tweak).

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, 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.
What am I missing?

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?

Ian C.




More information about the bazaar mailing list