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

From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2007-11-24 16:03:50

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.
* Create a tools/boostbook/index.html that redirs to the doc location.
* Ignore tools/buildbot for now since this may not be needed if Dave 
gets good results from Bitten.
* 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.
* Document tools/release. Or perhaps these are obsolete?
* Create a tools/wave/index.html to redir to the docs in libs/wave, if 
they exist?

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

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo