*Boost.async Documentation review*
*=============================*
*Overview*
The overview should be a narrative, answering the WHY question: "why should
a C++ developer be interested in this library?". The why answer should
cover the scenarios that this library addresses - from a scenario rather
than technology point of view. In other words, what problems do I have as a
developer that this library is the answer to. It is OK to add short
definitions of key terms - such as coroutine - as this is an opportunity to
explain any nuances in the interpretation of these terms that are unique or
particular to this library. Don't worry about insulting the intelligence of
the reader - the overview needs to paint the big picture and be relevant
for all levels of expertise that might use the library.
Good to see lots of linking, and the name of the author and version number.
Be consistent with capitalizations - table headings of "Coroutine types"
and "Synchronization Functions" - either start all with caps or all just
first word cap.
Code examples are good, but there is not a "copy" button for each sample
that will copy to the clipboard? Such a feature adds usability.
*Motivation*
The English is a little clunky "It based on boost.asio" - should for
example be "It is based on boost.asio". Or perhaps a rewrite such as "This
library, based on boost.asio, provides single threaded asynchronicity that
works well with existing libraries such as boost.beast, boost.mysql and
boost.redis." Words like "simple", "easy" and "very" add almost no meaning
and should be avoided. Not sure it is worth repeating similarities to
node.js or python - just mention once perhaps.
Do not use "&" instead of "and" in documentation. English throughout the
docs could use a gentle edit pass, for grammar and consistency.
Use *second *person in docs, to engage the reader more, for example: not
"this allows to write applications....." but "this allows *you *to write
applications....".
*Coroutine Primer*
Don't run two headings together, this is an issue throughout the
documentation. The first heading "Coroutine Primer" should have an
introductory paragraph (just a single sentence might suffice) that explains
what the section is about, and in particular what the section provides to
the reader.
*Async programming*
I like that this section is trying to explain the technology. No need for
"This library(boost.async) provides ...." just say "Boost.async
provides..." as this removes unnecessary words as is direct.
It is a matter of style, but I much prefer "For example..." over "E.g." it
is just easier to read smoothly, and similarly avoid "i.e." - replace this
with "that is" or appropriate wording.
The Stackless definition is a little weak - but like the link to the full
definition. Consider not attempting partial definitions, but instead add a
note such as:
Note:
Coroutines are *Stackless*. [with Stackless as a link to a full definition]
Awaitables
It is best to define technology with a purpose, not as part of other
technology. So introduce Awaitables with their purpose. For example:
*An "awaitable" function is designed to work with the co-routine mechanism,
allowing for asynchronous execution. When called, instead of running to
completion, it returns control back to the caller until a specific point,
marked by the `co_await` keyword, is reached. The function then pauses its
execution, allowing other operations to run, and resumes only when the
awaited condition is satisfied, making it a powerful tool for non-blocking
and concurrent programming scenarios, especially in contexts like I/O
operations or task scheduling.*
Similarly for Event Loops and any other technology term particular to async
Like the Previous, Up, Next links - aids navigation
*Tour*
Needs an intro paragraph.
Perhaps an intro paragraph to Promises, Tasks, Generator etc. explaining
their purposes - within the context of the library.
*Tutorial*
Intro paragraph that explains what the student will learn from the
tutorial. "By completing this tutorial, you will understand what coding
steps are necessary to ....".
Perhaps the tutorial should have numbered Steps to follow (1, 2, 3....)
where the steps are active - do this, do that etc.
Like the numbered comments though - though they could be added as comments
to the code - either way they are helpful.
Again, be consistent with headings - use either sentence caps ("Advanced
examples") or Title caps ("Advanced Examples") consistently. I prefer Title
caps.
Good to see many more examples, listed as "Advanced examples". Could
perhaps do with some general usage information - such as Create a Project,
copy and paste the code into which file of the project, etc.
*Design*
Needs an intro para.
Title capitalization consistency
*Reference*
Intro paragraph
Not sure why some code is in bold red?
Would have liked to see more tables - tables of properties, parameters,
options, class methods etc. - adds structure.
*Technical Background*
Intro para - what does this section contain?
Adding diagrams helps - perhaps a little more explanation of the flow of
control?
*Benchmarks*
Intro Para
=======================
Hope this is all clear
- Peter Turcan