[log] Documentation improvement suggestions - was :how to set attributes under multi-threaded application
Hi, Andrey Semashev said: I think the common formula "library design + tutorial + features description
+ reference" is the golden middle for medium-sized projects, like Boost.Log. Also, quite a few common case examples will help to get things started. The rest will come with experience.
I would like to give my limited feedback with the log docs about this very point : What I think might be a bit overhelming and don't help beginners with boost.log is the library design page itself. http://boost-log.sourceforge.net/libs/log/doc/html/log/design.html I mean the content organisation of the page, not the fact that it exists and I agree with you that it should be up front. The main problems with the page : A. there is a BIG bloc of text with almost no apparent hierarchy - that's a showstopper for a lot of people that will just click the "tutorial" link to see what it's really about; B. the scheme is clear technically but might be easier to read if it was to be read from left to right instead of right to left (at least because it uses english text); an alternative would have been from top to bottom : reading the scheme should follow the way data goes from loggers to sinks (in fact the current scheme looks like an inverted comics page to me...) Here are some suggestions to improve this page : 1. Structure the big block of text in several distinct parts, with titles. I think those parts already exists but they just lack obvious separations like just big titles. 2. Add links in the text to definitions from the previous page (Definitions). Reading the definitions first doesn't always make things really clear immediately. Often you read them used in context and then understand...or not if your forgot what it was. There are 9 definitions with several having the same beginning. It might be easier to the user to link to those simple definitions when they need them, when reading the library design text (might not be necessary after that?). 3. Invert the reading sens of the scheme or make it top to bottom. Obviously I'm an humble user, not an authority in the matter, but I hope it helps getting more users not stop at this page. Joël Lamotte
On 08/05/2011 01:37 AM, Klaim - Joël Lamotte wrote:
Hi,
I would like to give my limited feedback with the log docs about this very point : What I think might be a bit overhelming and don't help beginners with boost.log is the library design page itself. http://boost-log.sourceforge.net/libs/log/doc/html/log/design.html I mean the content organisation of the page, not the fact that it exists and I agree with you that it should be up front.
The main problems with the page : A. there is a BIG bloc of text with almost no apparent hierarchy - that's a showstopper for a lot of people that will just click the "tutorial" link to see what it's really about; B. the scheme is clear technically but might be easier to read if it was to be read from left to right instead of right to left (at least because it uses english text); an alternative would have been from top to bottom : reading the scheme should follow the way data goes from loggers to sinks (in fact the current scheme looks like an inverted comics page to me...)
Here are some suggestions to improve this page : 1. Structure the big block of text in several distinct parts, with titles. I think those parts already exists but they just lack obvious separations like just big titles. 2. Add links in the text to definitions from the previous page (Definitions). Reading the definitions first doesn't always make things really clear immediately. Often you read them used in context and then understand...or not if your forgot what it was. There are 9 definitions with several having the same beginning. It might be easier to the user to link to those simple definitions when they need them, when reading the library design text (might not be necessary after that?). 3. Invert the reading sens of the scheme or make it top to bottom.
Obviously I'm an humble user, not an authority in the matter, but I hope it helps getting more users not stop at this page.
Thanks, that is a most useful feedback. Yes, that page could use some improvement. I'll try to do something before the v2 release. Regarding the note about definitions. Does anyone know if it's possible to make a tooltip in quickbook?
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: Friday, August 05, 2011 1:45 AM To: boost@lists.boost.org Subject: Re: [boost] [log] Documentation improvement suggestions
Regarding the note about definitions. Does anyone know if it's possible to make a tooltip in quickbook?
As far as I know, this is not possible - but you can provide a link so that the puzzled can click drill down for more explanation. This is widely used to provide links to outside reference sources like Wikipedia. IMO they are very easy to add and very helpful to the less-well-informed reader. (One of the virtues of the Quickbook toolchain is that it can (and does) produce single file PDFs. These include hyperlinks, but not tooltips.) HTH Paul PS Don't forget too that John Maddock's Autoindex is now available. You can index C++ class, function etc names from the Doxygen reference, and also index terms (that the author thinks may be useful) in the text part. To ensure that the index takes the reader to the 'page' containing the index term, it is wise to avoid too long sections, so I would advise using sections quite freely - no bad thing anyway (as one reader of your draft commented). --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On 08/05/2011 12:42 PM, Paul A. Bristow wrote:
Regarding the note about definitions. Does anyone know if it's possible to make a tooltip in quickbook?
As far as I know, this is not possible - but you can provide a link so that the puzzled can click drill down for more explanation.
This is widely used to provide links to outside reference sources like Wikipedia. IMO they are very easy to add and very helpful to the less-well-informed reader.
Yes, it seems I'll have to put links instead. It's just too inconvenient IMHO since the link changes the viewing context of the reader.
(One of the virtues of the Quickbook toolchain is that it can (and does) produce single file PDFs. These include hyperlinks, but not tooltips.)
I see. Perhaps, tooltips could be added just for html output? I find them really useful in contexts like this, it's a shame to lose this tool.
PS Don't forget too that John Maddock's Autoindex is now available. You can index C++ class, function etc names from the Doxygen reference, and also index terms (that the author thinks may be useful) in the text part. To ensure that the index takes the reader to the 'page' containing the index term, it is wise to avoid too long sections, so I would advise using sections quite freely - no bad thing anyway (as one reader of your draft commented).
Interesting, I also implemented an indexing mechanism as a part of Boost.Log docs compilation so that it creates macros that add links to corresponding sections of reference. I'll take a look at Autoindex.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: Friday, August 05, 2011 10:18 AM To: boost@lists.boost.org Subject: Re: [boost] [log] Documentation improvement suggestions
On 08/05/2011 12:42 PM, Paul A. Bristow wrote:
Regarding the note about definitions. Does anyone know if it's possible to make a tooltip in quickbook?
As far as I know, this is not possible - but you can provide a link so that the puzzled can click drill down for more explanation.
This is widely used to provide links to outside reference sources like Wikipedia. IMO they are very easy to add and very helpful to the less-well-informed reader.
Yes, it seems I'll have to put links instead. It's just too inconvenient IMHO since the link changes the viewing context of the reader.
(One of the virtues of the Quickbook toolchain is that it can (and does) produce single file PDFs. These include hyperlinks, but not tooltips.)
I see. Perhaps, tooltips could be added just for html output? I find them really useful in contexts like this, it's a shame to lose this tool.
PS Don't forget too that John Maddock's Autoindex is now available. You can index C++ class, function etc names from the Doxygen reference, and also index terms (that the author thinks may be useful) in the text part. To ensure that the index takes the reader to the 'page' containing the index term, it is wise to avoid too long sections, so I would advise using sections quite freely - no bad thing anyway (as one reader of your draft commented).
Interesting, I also implemented an indexing mechanism as a part of Boost.Log docs compilation so
Is it possible that you can insert tooltips using http://www.javascriptkit.com/howto/toolmsg.shtml to pass XML item title http://www.w3schools.com/tags/att_standard_title.asp <p><abbr title="World Health Organization">WHO</abbr> was founded in 1948.</p> <p title="Free Web tutorials">W3Schools.com</p> directly from Quickbook with the Escape option (perhaps with a Quickbook template)? "Escape The escape mark-up is used when we don't want to do any processing. ''' escape (no processing/formatting) ''' Escaping allows us to pass XML markup to BoostBook or DocBook. For example: ''' <emphasis role="bold">This is direct XML markup</emphasis> ''' This is direct XML markup Important Be careful when using the escape. The text must conform to BoostBook/DocBook syntax. " But I've not tried it :-( that it
creates macros that add links to corresponding sections of reference. I'll take a look at Autoindex.
Sounds as though it does exactly what you want already? And you can add index terms that you want indexed from the text too. (The index terms use regex so that you can deal with plurals and similar variants.) Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
participants (3)
-
Andrey Semashev -
Klaim - Joël Lamotte -
Paul A. Bristow