[asio-users] Suggestions for improving the documentation

[Claudio Scordino]

Dear all.

Thank you for the effort that you put in developing Boost::asio. It's a
very powerful and useful library, indeed, but the documentation is not
very clear (googling for more documentation I saw that many other people
had this impression).

I've thought to provide you some suggestions about how the documentation
could be easily improved:

1. People often look at Asio just for networking.

Therefore, I suggest to change the order of sections in the overview:
- start with the anatomy
(http://www.boost.org/doc/libs/1_53_0/doc/html/boost_asio/overview/core/basics.html)
- then put networking
(http://www.boost.org/doc/libs/1_53_0/doc/html/boost_asio/overview/networking.html)
- then put the other concepts
(http://www.boost.org/doc/libs/1_53_0/doc/html/boost_asio/overview/core.html)

2. In the protocols page (i.e.
http://www.boost.org/doc/libs/1_53_0/doc/html/boost_asio/overview/networking/protocols.html)
show an example about how to connect to a given IP/port number, prior
than showing how to access a specific network service.

3. In the tutorial page
(http://www.boost.org/doc/libs/1_53_0/doc/html/boost_asio/tutorial.html)
add an example of asynchronous client (i.e., usage of async_connect).

4. Add a tutorial about how to implement the equivalent of the select()
syscall: given a certain amount of file descriptors, wake up an handler
as soon as one of these descriptors gets ready for I/O.

I hope that these suggestions will help you to further improve this library.

Best regards,

Claudio