Re: [boost] [website] Tools docs usability problem

From: Beman Dawes (bdawes_at_[hidden])
Date: 2007-11-25 11:03:45

Rene Rivera wrote:
> Beman Dawes wrote:
>> Some of the documentation that used to live within the boost-root/tools 
>> directory sub-tree has been moved to the 
>> website-root\public_html\beta\development directory.
> 
> Well, no. Only the regression testing instructions moved. And obviously 
> having two versions of the same test instructions is not something we 
> want as they will go out of sync, as they are now. All the other tools 
> are as they where before. One that needs to change are the Boost.Build 
> docs as Volodya needs to have those regenerated daily.
> 
>> That creates a usability problem because 
>> boost-root/tools/tool-name/index.html is no longer present.
> 
> We never had such files in the first place, AFAIK.
> 
>> When working 
>> with these tools, you are usually using either the command line or a GUI 
>> directory tree browser, not a web browser. Thus it is now a real pain in 
>> the anatomy to locate the docs since aren't right there where you are 
>> working. Worse yet, you may fail to realize there *are* any docs, and 
>> never look for them at all.
> 
> Hm... Quick survey:
> 
> tools/bcp/bcp.html
> tools/boostbook/doc/*.xml (end up in doc/html/boostbook.html)
> tools/build/index.html (redir to tools/build/v2/index.html)
> tools/buildbot (no docs yet)
> tools/common (no docs)
> tools/inspect/index.html
> tools/jam/index.html (redir to doc/html/jam.html)
> tools/litre (no docs)
> tools/quickbook/index.html (redir to tools/quickbook/doc/html/index.html)
> tools/regression/index.html (redir to tools/regression/doc/index.html)
> tools/release (no docs)
> tools/wave (no docs)
> 
> If we want to be consistent we would want to:
> 
> * Rename tools/bcp/bcp.html to index.html.

Or add an index.html that redirects to bcp.html. John, are you reading 
this-?

> * Create a tools/boostbook/index.html that redirs to the doc location.

Yes. Please go ahead and do that.

> * Ignore tools/buildbot for now since this may not be needed if Dave 
> gets good results from Bitten.

Yes, and Dave does seem to be getting good results from Bitten. I'll 
leave it up to you, but it seems to me that tools/buildbot should be 
deleted since we aren't actively using it. We can always retrieve it 
from SVN if needed.

> * Move tools/common to someplace more logical. It may not even be used 
> by now.
> * Finish writing the tools/inspect/doc/inspect.qbk docs and change the 
> index.html to a redir.
> * Have Dave and/or Daniel write docs for tools/litre. And also put in 
> copyright statements and general cleanup.

Yes to all three. Create tickets?

> * Document tools/release. Or perhaps these are obsolete?

I haven't looked at them, but next week when we start looking at release 
candidate creation I assume we will update or replace what is there.

 >...
> 
>> Perhaps we can solve the problem for tools in the same way. Each tool 
>> could have an index.html file that redirects to the actual docs 
>> location. With the docs now in a sub-tree that is not within the 
>> boost-root tree, the redirection requires a bit of logic:
>>
>>     If index.html is a local working copy, redirect to beta.boost.org/...
>>     otherwise redirect to www.boost.org/...
>>
>> Is this the best solution? Is Javascript capable of doing that?
> 
> We don't need that solution. The simple redirect is fine for just about 
> all tools docs. The one exception is the testing docs. I think we can 
> get away with a short note mentioning that the docs for running tests 
> are in the web site. With a link to beta.boost.org for now. When we 
> switch to the live site we can change that link.

A short note is fine. Could you please add it?

Thanks,

--Beman