[chrono] Documentation suggestions
Hi, I have a few remarks/suggestions for the documentation of Boost.Chrono: *General: *http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/index.htm... There are several sections which attract my attention when trying to get a grip on the library: * Getting Started * Tutorial * Examples Each of those looks a bit like a random collection of valuable hints to me (sorry, if I missed the pattern). My personal troubles in understanding the basics are documented in the mail referenced in the tutorial section. I think it would be worth it to reorganize all three into one section (e.g. tutorial) which shows how to utilize the different parts of the library. For instance with the following subsections: * Clocks (including stopwatch and thread_clock) * Formatters * Reporters * Conversions (see also Tutorial section below) * ...? Each section would contain usage patterns and complete sample programs. *Users Guide: *http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr... * Personally, I would move the references section to the appendices (I clicked there several times when I really wanted to see the Reference section) *Reference: *http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr... * thread_clock is missing in the reference section * typo "chorno.hpp>" on several pages *Examples:* http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr... * There are several hints like "See the file i_dont_like_the_default_duration_behavior.cpp". It would be nice to have a working link to the file instead * Some examples are not linked to a file. I think it would be good to have a working sample file for each example *Tutorial:* http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr... * The section "How to define a thread clock" is now obsolete, isn't it? thread_clock is now integral part of chrono. * An example on how to use the thread_clock would be very helpful. * An example on how to obtain a duration in some unit would be helpful See here (http://lists.boost.org/boost-users/2010/04/58204.php) for what I meant with the last item. The answers by Howard Hinnant in this mail were extremely helpful and could probably be re-used in the tutorial. Regards, Roland
----- Original Message ----- From: "Roland Bock" <rbock@eudoxos.de> To: <boost@lists.boost.org> Sent: Wednesday, June 23, 2010 3:27 PM Subject: [boost] [chrono] Documentation suggestions
Hi,
I have a few remarks/suggestions for the documentation of Boost.Chrono:
*General: *http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/index.htm...
There are several sections which attract my attention when trying to get a grip on the library:
* Getting Started * Tutorial * Examples
Each of those looks a bit like a random collection of valuable hints to me (sorry, if I missed the pattern). My personal troubles in understanding the basics are documented in the mail referenced in the tutorial section.
I have try to follow the structure of Boost.Proto. Getting started include just the associated Hello World example. The follows the tutorial that tries to explain to the user how to use the library. Last, the examples section should contain complete examples without too much explanation on how the things are done. I will see if there are some Examples that could be better in the Tutorial section.
I think it would be worth it to reorganize all three into one section (e.g. tutorial) which shows how to utilize the different parts of the library. For instance with the following subsections:
* Clocks (including stopwatch and thread_clock) * Formatters * Reporters * Conversions (see also Tutorial section below) * ...?
I will see if this decomposition makes clearer the tutorial.
Each section would contain usage patterns and complete sample programs.
As I said before, I reserve the complete sample programs to the Examples section.
*Users Guide: *http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr...
* Personally, I would move the references section to the appendices (I clicked there several times when I really wanted to see the Reference section)
I hope you don't loose to much time. I think that this is due to the fact I have decomposed the Reference section and the header files are not visible from the root table of contents. What about renaming it "External Resources"?
*Reference: *http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr...
* thread_clock is missing in the reference section
Oups. I missed that. I will add.
* typo "chorno.hpp>" on several pages
done.
*Examples:* http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr...
* There are several hints like "See the file i_dont_like_the_default_duration_behavior.cpp". It would be nice to have a working link to the file instead
* Some examples are not linked to a file. I think it would be good to have a working sample file for each example
I will add the links for all the examples.
*Tutorial:* http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr...
* The section "How to define a thread clock" is now obsolete, isn't it? thread_clock is now integral part of chrono.
Yes, now thread_clok is part of the library. Even in this case I find that this is good way to show how to define a clock.
* An example on how to use the thread_clock would be very helpful. There is no difference respect to other Clocks. I will add an example.
* An example on how to obtain a duration in some unit would be helpful See here (http://lists.boost.org/boost-users/2010/04/58204.php) for what I meant with the last item. The answers by Howard Hinnant in this mail were extremely helpful and could probably be re-used in the tutorial.
Yes the answer of Howard was very clear. I will add a section based on the Howard response.;
Regards,
Roland
Thanks for your comments, Vicente
vicente.botet wrote:
----- Original Message ----- From: "Roland Bock" <rbock@eudoxos.de> To: <boost@lists.boost.org> Sent: Wednesday, June 23, 2010 3:27 PM Subject: [boost] [chrono] Documentation suggestions
Hi,
I have a few remarks/suggestions for the documentation of Boost.Chrono:
*General: *http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/index.htm...
There are several sections which attract my attention when trying to get a grip on the library:
* Getting Started * Tutorial * Examples
Each of those looks a bit like a random collection of valuable hints to me (sorry, if I missed the pattern). My personal troubles in understanding the basics are documented in the mail referenced in the tutorial section.
I have try to follow the structure of Boost.Proto. Getting started include just the associated Hello World example.
I looked at Proto: Sure, "Getting Started" contains just two "Hello World" expamples, but it also uses them to show or give hints to all sorts of usage aspects. The Getting Started section in Chrono just shows one example which looks like a more verbose version of boost::progress_timer. Nice, handy, but not exactly exciting. Don't get me wrong. This is a good example, of course. But chrono offers so much more (like the thread clock for instance, or suspending clocks, or reading out values, or conversions...). I think you should show more aspects of what could be done with chrono. Make the reader eager to read on. Citing from Proto's "Getting Started": "Hopefully, this gives you an idea of what sorts of things Proto can do for you. But this only scratches the surface. The rest of this users' guide will describe all these features and others in more detail."
The follows the tutorial that tries to explain to the user how to use the library. Last, the examples section should contain complete examples without too much explanation on how the things are done. I will see if there are some Examples that could be better in the Tutorial section.
I think it would be worth it to reorganize all three into one section (e.g. tutorial) which shows how to utilize the different parts of the library. For instance with the following subsections:
* Clocks (including stopwatch and thread_clock) * Formatters * Reporters * Conversions (see also Tutorial section below) * ...?
I will see if this decomposition makes clearer the tutorial.
I am not sure if my suggestion is the best. But I am pretty sure that starting the tutorial with "how to create your own clock" is not optimal. It was a bit of a turn-off for me, at least. I think dedicated sub sections (with separate files) are helpful, because they allow the reader to easily skip the parts which they consider irrelevant for their purposes. In my case, I would have skipped formatters and reporters. I'd start each subsection with the really simple things, one- to three-liners. Then move on to the more complex ones.
*Users Guide: *http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr...
* Personally, I would move the references section to the appendices (I clicked there several times when I really wanted to see the Reference section)
I hope you don't loose to much time. I think that this is due to the fact I have decomposed the Reference section and the header files are not visible from the root table of contents. What about renaming it "External Resources"?
I was exaggerating, of course :-) External References is cool, I think
*Tutorial:* http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chr...
* The section "How to define a thread clock" is now obsolete, isn't it? thread_clock is now integral part of chrono.
Yes, now thread_clok is part of the library. Even in this case I find that this is good way to show how to define a clock.
Understood. In that case I would suggest a subsection for "Defining custom clocks" for those whose usecases are not covered by the existing clocks. I assume there are some basic concepts to be followed when defining my own clock? They should be explained. People not interested in creating their own clocks could then simply skip this section.
Thanks for your comments, Vicente
Sure thing :-) Thanks for the library! I am looking forward to the day it gets accepted into boost! Regards, Roland
participants (2)
-
Roland Bock -
vicente.botet