[website] Tools docs usability problem
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. That creates a usability problem because boost-root/tools/tool-name/index.html is no longer present. 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. In the boost-root/libs directory tree, we solve this same problem by providing an index.html file for each library that automatically redirects to wherever the docs for the library actually live. Because that is generally a relative link, it finds either the web version or the version within the local disk tree, depending on whether you are browsing the web or a local working copy. This is expected behavior, and works very well in practice. If you are using a working copy, you get the docs as of that working copy. If you are looking at the web site, you get the docs matching the web site release. 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? --Beman
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
Rene Rivera wrote:
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)
The docs for the Wave tool are part of the library docs and the old tools overview page used to redirect there. Regards Hartmut
Hartmut Kaiser wrote:
Rene Rivera wrote:
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)
The docs for the Wave tool are part of the library docs and the old tools overview page used to redirect there.
Ah, yes I forgot to mention the tools/index.html file. Which indeed does have the link for Wave go to the corresponding library docs. It also have links for the other tools going to the obvious places. -- -- 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
Rene Rivera wrote:
Hartmut Kaiser wrote:
The docs for the Wave tool are part of the library docs and the old tools overview page used to redirect there.
Ah, yes I forgot to mention the tools/index.html file. Which indeed does have the link for Wave go to the corresponding library docs. It also have links for the other tools going to the obvious places.
I just deleted my tools/wave and did a fresh update. No index.html. Are you sure your working copy actually reflects the current trunk:-) --Beman
Beman Dawes wrote:
Rene Rivera wrote:
Hartmut Kaiser wrote:
The docs for the Wave tool are part of the library docs and the old tools overview page used to redirect there. Ah, yes I forgot to mention the tools/index.html file. Which indeed does have the link for Wave go to the corresponding library docs. It also have links for the other tools going to the obvious places.
I just deleted my tools/wave and did a fresh update. No index.html. Are you sure your working copy actually reflects the current trunk:-)
I was referring, correctly, to BOOST_ROOT/tools/index.html, not the non-existent BOOST_ROOT/tools/wave/index.html. -- -- 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
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
On Sun, Nov 25, 2007 at 04:27:24PM -0000, John Maddock wrote:
Beman Dawes wrote:
* Rename tools/bcp/bcp.html to index.html.
Or add an index.html that redirects to bcp.html. John, are you reading this-?
Yep: Added the redirect file.
A redirect is not necessarily supported in each HTML browser. The standard doesn't enforces it. But you added a "Automatic redirection failed, please go to <a href="doc/html/index.html">bcp.html</a>" so it is OK. This file tools/bcp/index.html is a new one, right? Why does the copyright mention 2001 instead of 2007? I would also use lower HTML tags such as <p> instead of <P> to be HTML 4 compatible. Jens
Jens Seidel wrote:
On Sun, Nov 25, 2007 at 04:27:24PM -0000, John Maddock wrote:
Beman Dawes wrote:
* Rename tools/bcp/bcp.html to index.html.
Or add an index.html that redirects to bcp.html. John, are you reading this-?
Yep: Added the redirect file.
A redirect is not necessarily supported in each HTML browser. The standard doesn't enforces it. But you added a "Automatic redirection failed, please go to <a href="doc/html/index.html">bcp.html</a>" so it is OK.
This file tools/bcp/index.html is a new one, right? Why does the copyright mention 2001 instead of 2007?
Because it was a lazy cut and paste from another file, now fixed.
I would also use lower HTML tags such as <p> instead of <P> to be HTML 4 compatible.
Also fixed. John.
Beman Dawes wrote:
Rene Rivera wrote:
Beman Dawes wrote:
If we want to be consistent we would want to:
* Create a tools/boostbook/index.html that redirs to the doc location.
Yes. Please go ahead and do that.
Done.
* 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.
I moved it back to the sandbox, whence it came from, for now <http://svn.boost.org/trac/boost/changeset/41362>.
* Move tools/common to someplace more logical. It may not even be used by now.
Removed it, as I had already put it back into the inspect sources where it was used.
* 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?
Done <http://svn.boost.org/trac/boost/ticket/1478> <http://svn.boost.org/trac/boost/ticket/1479>.
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?
Done, along with some of the above changes <http://svn.boost.org/trac/boost/ticket/1479>. -- -- 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
Rene Rivera wrote:
... Done.
... I moved it back to the sandbox, whence it came from, for now <http://svn.boost.org/trac/boost/changeset/41362>.
... Removed it, as I had already put it back into the inspect sources where it was used.
... Done <http://svn.boost.org/trac/boost/ticket/1478> <http://svn.boost.org/trac/boost/ticket/1479>.
... Done, along with some of the above changes <http://svn.boost.org/trac/boost/ticket/1479>.
Thanks! --Beman
participants (5)
-
Beman Dawes -
Hartmut Kaiser -
Jens Seidel -
John Maddock -
Rene Rivera