Documentation links home
Hi, I was looking at http://www.boost.org/libs/smart_ptr/smart_ptr.htm and I was surprised to find that there was no link to the main boost page. There are many other doc pages that dont have a link either to their own index pages or the boost index page. (Though many others do e.g http://www.boost.org/doc/html/date_time.html .) Anyone arriving at pages with no link to their parents has no direct way to find e.g what is boost or how/ where to download the boost libraries. That aside it is annoying when browsing that one has no means to get back up the tree. URLs such as smart pointer above are frequently posted on eg comp.lang.++, but the lack of any simple means to get up the tree must leave many potential users stranded and frustrated. Shouldnt it possible at least to get from any page in a libraries documentation to its main index page (e.g http://www.boost.org/libs/smart_ptr/shared_ptr.htm) and ideally http://www.boost.org/ too? (FWIW You could at least make the boost logo a link to http://www.boost.org/) Just a thought. Andy Little
On Sat, 24 Sep 2005 12:40:23 +0100, Andy Little wrote
Hi,
I was looking at http://www.boost.org/libs/smart_ptr/smart_ptr.htm and I was surprised to find that there was no link to the main boost page. There are many other doc pages that dont have a link either to their own index pages or the boost index page. (Though many others do e.g http://www.boost.org/doc/html/date_time.html .)
I think you'll find that all the libraries that use boost-book (as date-time does) have links to the home as well as a common look and feel. Libraries with hand-coded docs are all over the map.
Anyone arriving at pages with no link to their parents has no direct way to find e.g what is boost or how/ where to download the boost libraries. That aside it is annoying when browsing that one has no means to get back up the tree. URLs such as smart pointer above are frequently posted on eg comp.lang.++, but the lack of any simple means to get up the tree must leave many potential users stranded and frustrated. Shouldnt it possible at least to get from any page in a libraries documentation to its main index page (e.g http://www.boost.org/libs/smart_ptr/shared_ptr.htm) and ideally http://www.boost.org/ too? (FWIW You could at least make the boost logo a link to http://www.boost.org/)
Yes, this would be ideal, but it is alot of work to get all the docs into a consistent form that everyone can agree. Even if we get agreement to move toward a common standard (which I believe we should do) there will be a tremendous amount of work to get all of boost converted over... Jeff
Jeff Garland wrote:
I think you'll find that all the libraries that use boost-book (as date-time does) have links to the home as well as a common look and feel. Libraries with hand-coded docs are all over the map. Hmm, that makes sense. Yes, this would be ideal, but it is alot of work to get all the docs into a consistent form that everyone can agree. Even if we get agreement to move toward a common standard (which I believe we should do) there will be a tremendous amount of work to get all of boost converted over... c.l.boost.devel just mentioned a 'documentation wizard', (in the hacker sense of a genius, not the MS sense of a program to run the program :D), so maybe you will get your wish...
On Mon, 26 Sep 2005 11:59:36 +1200, Simon Buchan wrote
Yes, this would be ideal, but it is alot of work to get all the docs into a consistent form that everyone can agree. Even if we get agreement to move toward a common standard (which I believe we should do) there will be a tremendous amount of work to get all of boost converted over...
c.l.boost.devel just mentioned a 'documentation wizard', (in the hacker sense of a genius, not the MS sense of a program to run the program :D), so maybe you will get your wish...
From some off-list moderator discussion I suspect that the role of the documentation wizard will be mostly to ensure quality and completeness of the written docs more than the 'format -- but we are leaving the details up to Rob so maybe he'll want to do something with setting additional doc standards such as always ensuring a link back to the main page.
This issue also intersects with work that Rene Rivera and others have been doing to modernize and improve the web site. Navigation is a big part of that redesign work which obviously hasn't made it to the whole site. BTW, contributions of time on the web redesign would surely be accepted -- so anyone with skills and some free time might want to ask on the developer list how best to contribute... Jeff
"Jeff Garland"
On Mon, 26 Sep 2005 11:59:36 +1200, Simon Buchan wrote
Yes, this would be ideal, but it is alot of work to get all the docs into a consistent form that everyone can agree. Even if we get agreement to move toward a common standard (which I believe we should do) there will be a tremendous amount of work to get all of boost converted over...
c.l.boost.devel just mentioned a 'documentation wizard', (in the hacker sense of a genius, not the MS sense of a program to run the program :D), so maybe you will get your wish...
From some off-list moderator discussion I suspect that the role of the documentation wizard will be mostly to ensure quality and completeness of the written docs more than the 'format -- but we are leaving the details up to Rob so maybe he'll want to do something with setting additional doc standards such as always ensuring a link back to the main page.
This issue also intersects with work that Rene Rivera and others have been doing to modernize and improve the web site. Navigation is a big part of that redesign work which obviously hasn't made it to the whole site. BTW, contributions of time on the web redesign would surely be accepted -- so anyone with skills and some free time might want to ask on the developer list how best to contribute...
Jeff
I dont think that every page needs a common look but I do think links to the libraries doc main page and the boost main index should be required on very documentation page. . I've already modified some of my local documentation by adding basic links in basic html. I brought this subject up so I'm happy to offer offer my services to hand modify boost doc html pages if that will help... Who should I get in touch with ?. regards Andy Little
Sorry . I should have said in the original message: This thread has been crossposted from comp.lib.boost.user. regards Andy Little
participants (3)
-
Andy Little -
Jeff Garland -
Simon Buchan