Re: [boost] Asynchronous library now in Boost Library Incubator
I'm trying to digest the docs for this monster work.
One things that strikes me immediately is that the doc preparation does not use code snippets, and so code is in boring old black'n'white rather than colored syntax. For me, that makes it significantly harder to read (and understand) the code examples.
Ok, I'll see if I can improve this.
It also means that one doesn't have the assurance that 'What You See is What Compiles'.
For most features, the doc provides a link to an example, which I regularly compile.
(I've also having trouble finding things in all the plentiful 'good stuff'. But that's a common (and largely still unsolved) problem with all documentation.)
Paul
Please let me know what is the "good stuff" for you and I'll make it more visible. Cheers, Christophe
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Christophe Henry Sent: 30 November 2016 20:34 To: boost@lists.boost.org Subject: Re: [boost] Asynchronous library now in Boost Library Incubator
I'm trying to digest the docs for this monster work.
One things that strikes me immediately is that the doc preparation does not use code snippets, and so code is in boring old black'n'white rather than colored syntax. For me, that makes it significantly harder to read (and understand) the code examples.
Ok, I'll see if I can improve this.
It also means that one doesn't have the assurance that 'What You See is What Compiles'.
For most features, the doc provides a link to an example, which I regularly compile.
(I've also having trouble finding things in all the plentiful 'good stuff'. But that's a common (and largely still unsolved) problem with all documentation.)
Please let me know what is the "good stuff" for you and I'll make it more visible.
It isn't visibility that's the problem, it's the seeing the wood for the trees. The more good stuff you write, the more trees there are and the more difficult it is to get to what you want. Indexes and the 'find key' are two helpers. With html, you can't use the 'find key' in the *whole* docs, so you can't get to all the references to, say', "future". Searching *all* the document is why Google does so well for us. I googled "boost quickbook code snippets" and got to a page, but I had to use the 'find key' to get to the info I wanted to give you. Code Snippet Markup Note how the code snippets in stub.cpp get marked up. We use distinguishable comments following the form: //[furtures_example_1 some code here ... //] [/furtures_example_1] (Hint: A [/furtures_example_1] comment here helps you avoid mismatched 'brackets' confusion). My experience of maintaining Boost.Math is that it is all too easy to alter the example code, but forget to alter the copy'n'pasted part into the docs. Recommended. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
participants (2)
-
Christophe Henry -
Paul A. Bristow