Re: [boost] [async-mqtt5] Formal review starts today

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@lists.boost.org> wrote:

On Sun, Oct 20, 2024 at 10:53 AM Ivica Siladic 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