Re: [async-mqtt5] Formal review starts today

From: Peter Turcan (peterturcan_at_[hidden])
Date: 2024-10-21 20:25:40

Klemens,

I have reviewed the documentation for the MQTT5 library and here are
my comments - hope they are useful!

Overall there is a lot of technical documentation, a decent range of
examples, and a lot of linking to internal and relevant external topics -
all of which is good. I agree with comments above that the "Introduction"
is weak and could use some work. The first paragraphs of an introduction
should critically answer the "why" question - "why should I be interested
in this library?". The "what" question should be answered, as it briefly
is, but is a lot less important than the why question. Another
interpretation of the why question is "what does this do for me?" and a
detailed answer is good and seems to be addressed in some of the email
responses above.

The API reference is good and fairly comprehensive - though I might ask if
there is enough information on the function calls. In particular I would
like to know what error messages/exceptions can be thrown by which
functions. In other words a table of all - or the most common - errors that
might be the response to a function call would be good information to add
to the page on each function - which at the moment is a tad thin on
content. Secondly, a link to an example containing use of that function
would be useful - should an example exist.

When reading the Introduction I came up with the following nits, though the
comments apply throughout the documentation.

Nits
The following are minor grammatical/spelling issues:

1. remove the word "very" from the following sentence as it adds nothing:
*The aim of Async.MQTT5 is to provide a very simple asynchronous C++
interface for application developers.*

2. Add a sentence after this one, describing what the "*compatible with
completion tokens*" implies - what does this enable (otherwise what goes
through the reader's mind can be "so what?"):

*The Client's asynchronous functions are compatible with all completion
tokens supported by Boost.Asio.*

3. Consider changing the "Features" section to a table, with two columns
with headings "Feature" and "Description". The first column is the feature
(such as *Support for QoS 0, QoS 1, and QoS 2*) the second is a description
including links. This will force the authors to add descriptions to the
features which currently do not have one (3 at present). The focus of the
description should be to answer the question "why is this useful?" rather
than what it is.

4. Similarly to the use of the word "very" described above, the word
"simple" adds pretty much nothing to the understanding of a sentence -
consider removing "simple" from:

*The following example illustrates a simple scenario of configuring a
Client and publishing a "Hello World!" Application Message with QoS 0.*

[consider searching all the docs for "simple", "very" and removing them -
just makes the text sharper and easier to read]
[great to have this example, and a link to more examples]

5. Consider moving the "*When to use*" section up to the top as a
subheading under "*Introduction*"

6. Consistently use "*an MQTT*" and not "*a MQTT*". This is because M is
pronounced "em" (so it starts with a vowel in the mind of the reader).
Mostly you have used "an" but not consistently as here:

*Your application uses Boost.Asio and requires integrating a MQTT Client.*

[again, search the docs for "a MQTT" and update to "an" appropriately]

7. Consider changing the "*Requirements*" heading to "*Getting Started*"
and move it above the "*Examples*" section - as it contains essential
information to get anything going. Also add this info from Git if is
current:
Using the library <https://github.com/mireo/async-mqtt5/#using-the-library>

   1. Download Boost <https://www.boost.org/users/download/>, and add it to
   your include path.
   2. If you use SSL, download OpenSSL <https://www.openssl.org/>, link the
   library and add it to your include path.
   3. Add Async.MQTT5's include folder to your include path.

8. Remove the word "Only" - all the necessary meaning is provided by the
word "If":

*Only if you require an SSL connection by using boost::asio::ssl::stream.*

9. Perhaps add a link to the Boost license if that is the license that is
pertinent, or a link to the correct license if not.

10. Consider consistently using Title Capitalization in all headings
throughout the docs - does look better than the current Sentence Caps, so:

*Using the library*, becomes

*Using the Library*

11. Perhaps comment on whether the library is "modularized" and fits neatly
into the Boost super project.

12. Is the only dependency Boost.asio? If there are other dependencies that
are not sub-dependencies of Boost.asio, perhaps list them.

13. Consider commenting on performance - are there other similar libraries
out there you have compared perf with?

All I have for now.

For the record I am the Technical Writer for C++ Alliance.

best

- Peter Turcan

On Sun, Oct 20, 2024 at 11:12 AM Vinnie Falco via Boost <
boost_at_[hidden]> wrote:

> On Sun, Oct 20, 2024 at 10:53 AM Ivica Siladic <ivica.siladic_at_[hidden]>
> wrote:
>
> > Here are the answers to your questions. These should probably not go into
> > official documents but rather into separate doc.
> >
>
> Thank you so much.
>
> This information is very relevant and I think it should be in the official
> documentation (that is, the library HTML documentation which is part of
> every release). Assuming mqtt5 is accepted, I prefer people who evaluate
> Boost to see that it has a best-of-class MQTT client, as IoT is an area
> where C++ has considerable strengths.
>
> Exposition which reveals the mind of the authors and their design
> principles greatly enhances the perception of the library's value. Knowing
> it is used in production environments increases confidence that the library
> will be actively improved and maintained.
>
> Authors who propose libraries in the future who are reading this take note:
> these things make the submission look better :)
>
> Thanks
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>