Why is the boost documentation so bad?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

Why is the boost documentation so bad?

Boost - Dev mailing list
Hello,

I really love to use boost libraries in my project, but I always wonder, for such an accomplished project, why is the
documentation so bad?

A few examples:

I want to get familiar with http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/. What do I need to include? Neiter
the tutorial, the reference or the usage guidelines mention a #include line. This is something which stroke me quite
often at various boost libs.

Also with the ptr_container lib, I want to find the refrence for the ptr_vector::insert function. I got to scan the
reference pages of all members of it's class hierarchy to find the insert() function (it's in ptr_sequence_adapter).

References and example code often have no syntax highlightning and no linking and it's extremely hard to find
documentation for a specific symbol, or from there, to jump to the source code.

I would really like to have a more uniform and a documentation that not feels like a annotated source code dump.

I use doxygen for my own projects and I know it can generate nicely looking, with syntax highlightning and linked
documentation.

Please, don't take this offensive, it's just some feedback I wanted to give a long time.

Best,
Florian

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
Another example which just occured to me:

http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/doc/ptr_inserter.html tells me how to copy elements, but I got
to grep the source code to find out I need to include #include <boost/ptr_container/ptr_inserter.hpp> to get the
back_inserter. Documentation was not helpful there.


Am 08.09.2017 um 10:21 schrieb Florian Lindner:

> Hello,
>
> I really love to use boost libraries in my project, but I always wonder, for such an accomplished project, why is the
> documentation so bad?
>
> A few examples:
>
> I want to get familiar with http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/. What do I need to include? Neiter
> the tutorial, the reference or the usage guidelines mention a #include line. This is something which stroke me quite
> often at various boost libs.
>
> Also with the ptr_container lib, I want to find the refrence for the ptr_vector::insert function. I got to scan the
> reference pages of all members of it's class hierarchy to find the insert() function (it's in ptr_sequence_adapter).
>
> References and example code often have no syntax highlightning and no linking and it's extremely hard to find
> documentation for a specific symbol, or from there, to jump to the source code.
>
> I would really like to have a more uniform and a documentation that not feels like a annotated source code dump.
>
> I use doxygen for my own projects and I know it can generate nicely looking, with syntax highlightning and linked
> documentation.
>
> Please, don't take this offensive, it's just some feedback I wanted to give a long time.
>
> Best,
> Florian
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Thu, Sep 7, 2017 at 7:21 PM, Florian Lindner via Boost
<[hidden email]> wrote:
> why is the documentation so bad?

I think it is unfair to say that every library has bad documentation.

I would like your opinion, what do you think of these docs?
<http://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/ref/boost__beast__http__async_write/overload1.html>

I realize that quality may vary from library to library. Perhaps you
can open an issue for your specific documentation problem against that
particular library?

Thanks

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list


Am 08.09.2017 um 10:51 schrieb Vinnie Falco via Boost:
> On Thu, Sep 7, 2017 at 7:21 PM, Florian Lindner via Boost
> <[hidden email]> wrote:
>> why is the documentation so bad?
>
> I think it is unfair to say that every library has bad documentation.

You're right of course. This is just an impression I got from the libraries I worked with so far, which logging, test,
ptr_container and some others.

> I would like your opinion, what do you think of these docs?
> <http://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/ref/boost__beast__http__async_write/overload1.html>

This is really much better than most I've seen at other parts of boost.

>
> I realize that quality may vary from library to library. Perhaps you
> can open an issue for your specific documentation problem against that
> particular library?

I can and I will. But I wanted to bring this general issue (and from my perception it is a general issue, with best an
exception) here first.

Best,
Florian

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 8/09/2017 14:21, Florian Lindner wrote:
> I really love to use boost libraries in my project, but I always
> wonder, for such an accomplished project, why is the documentation so
> bad?

In many cases, probably the same reason any other technical
documentation is bad -- it is written by the original
developer/maintainer, who has a mental model of how everything fits
together and on occasion will omit things because they don't realise
what sort of questions people will have or that what seems self-evident
to them might not be to others.

I'm sure pull requests with suggested improvements would be welcomed.

> I want to get familiar with
> http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/. What do I
> need to include? Neiter the tutorial, the reference or the usage
> guidelines mention a #include line. This is something which stroke
> me quite often at various boost libs.
This is one of the older libraries in Boost, which might be a factor.

Most Boost libraries provide a single "master" header file which you can
include to get all components of the library, and this is the typical
usage when getting started.  You might later narrow to a subset once you
know exactly which parts you want to use -- and generally your IDE can
then help you locate which specific subfiles they're in.

Unfortunately different Boost libraries have different conventions for
the name of this master header file, but generally one of the following
will do the trick:

   * <boost/lib_name.hpp>
   * <boost/lib_name/lib_name.hpp>
   * <boost/lib_name/all.hpp>


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 09/08/17 06:04, Florian Lindner via Boost wrote:

>
> Am 08.09.2017 um 10:51 schrieb Vinnie Falco via Boost:
>> On Thu, Sep 7, 2017 at 7:21 PM, Florian Lindner via Boost
>> <[hidden email]> wrote:
>>> why is the documentation so bad?
>>
>> I think it is unfair to say that every library has bad documentation.
>
> You're right of course. This is just an impression I got from the libraries I worked with so far, which logging, test,
> ptr_container and some others.

I'm wondering what are your complaints about Boost.Log docs and how do
you think it could be improved.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 08-09-17 05:04, Florian Lindner via Boost wrote:
> I can and I will. But I wanted to bring this general issue (and from my perception it is a general issue, with best an
> exception) here first.

Why? What did you expect to learn?

To me it seems unconstructive, a waste of time. You wouldn't like it if
my approach to you was "Why are you always complaining so hard?".

$0.02



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
> but I got to grep the source code to find out I need to include #include
<boost/ptr_container/ptr_inserter.hpp> to get the back_inserter.
Documentation was not helpful there.

Well, boost is free software, maintained by a dedicated and much
under-celebrated community of heroes.

In my view it has single-handedly rescued c++ from oblivion and is the
breeding ground for all ideas that eventually go into the standard as
language improvements.

If the documentation is not helpful, it is up to us, the grateful users of
boost, to offer an improvement by submitting a commit, or at least a bug
report to a maintainer.

Otherwise we're just being leaches.

For me, I could not have completed my many programs without:

boost.log,
boost.asio,
boost.algorithm,
boost.msm,
boost.variant,
boost.shared_ptr (before it was in c++),
boost.serialization,
boost.thread (ditto),
boost.regex (ditto),

It's also the only 3rd party library I have used which has given me no
problems (apart from that one time when clang and apple clan diverged over
the keyword thread_local) - even that was fixed in the next release.

The existence of boost has literally saved me writing, testing and fixing
hundreds of thousands of lines of code.

From me, thank you to everyone who has contributed to boost. You are the
internet's finest.






On 8 September 2017 at 04:27, Florian Lindner via Boost <
[hidden email]> wrote:

> Another example which just occured to me:
>
> http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/doc/
> ptr_inserter.html tells me how to copy elements, but I got
> to grep the source code to find out I need to include #include
> <boost/ptr_container/ptr_inserter.hpp> to get the
> back_inserter. Documentation was not helpful there.
>
>
> Am 08.09.2017 um 10:21 schrieb Florian Lindner:
> > Hello,
> >
> > I really love to use boost libraries in my project, but I always wonder,
> for such an accomplished project, why is the
> > documentation so bad?
> >
> > A few examples:
> >
> > I want to get familiar with http://www.boost.org/doc/libs/
> 1_65_1/libs/ptr_container/. What do I need to include? Neiter
> > the tutorial, the reference or the usage guidelines mention a #include
> line. This is something which stroke me quite
> > often at various boost libs.
> >
> > Also with the ptr_container lib, I want to find the refrence for the
> ptr_vector::insert function. I got to scan the
> > reference pages of all members of it's class hierarchy to find the
> insert() function (it's in ptr_sequence_adapter).
> >
> > References and example code often have no syntax highlightning and no
> linking and it's extremely hard to find
> > documentation for a specific symbol, or from there, to jump to the
> source code.
> >
> > I would really like to have a more uniform and a documentation that not
> feels like a annotated source code dump.
> >
> > I use doxygen for my own projects and I know it can generate nicely
> looking, with syntax highlightning and linked
> > documentation.
> >
> > Please, don't take this offensive, it's just some feedback I wanted to
> give a long time.
> >
> > Best,
> > Florian
> >
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/
> mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 9/8/17 12:26 AM, Gavin Lambert via Boost wrote:

> On 8/09/2017 14:21, Florian Lindner wrote:
>> I really love to use boost libraries in my project, but I always
>> wonder, for such an accomplished project, why is the documentation so
>> bad?
>
> In many cases, probably the same reason any other technical
> documentation is bad -- it is written by the original
> developer/maintainer, who has a mental model of how everything fits
> together and on occasion will omit things because they don't realise
> what sort of questions people will have or that what seems self-evident
> to them might not be to others.

This is basically the correct answer.  It's not a Boost problem, it's a
software development problem.  As software gets more sophisticated, the
problem becomes worse.

In the past I've had a lot to say about this problem.  I always carp
about it in boost reviews and offer what I believe to be constructive
suggestions.  But still it's a problem.  I've come to believe that I
understand the source of this problem and what the route to the solution
is.  For those who might be interesting, I will be expounding on this
subject at the upcoming CPPCon 2017:

https://cppcon2017.sched.com/event/BgtD/how-to-write-effective-documentation-for-c-libraries-with-minimal-effort

See you there.

Robert Ramey


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
Den 08-09-2017 kl. 04:21 skrev Florian Lindner via Boost:

> Hello,
>
> I really love to use boost libraries in my project, but I always wonder, for such an accomplished project, why is the
> documentation so bad?
>
> A few examples:
>
> I want to get familiar with http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/. What do I need to include? Neiter
> the tutorial, the reference or the usage guidelines mention a #include line. This is something which stroke me quite
> often at various boost libs.

While it would help to have the docs upgraded/improved the front page
has a link to a section called "library headers":

http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/doc/headers.html

Boris Schäling has an awesome online book:

https://theboostcpplibraries.com/

full of nice examples.

kind regards

Thorsten

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
Florian Lindner wrote:
> why is the documentation so bad?

The fundamental answer to your question is that Boost libraries
are subject to peer review, and in the standard invitation to
submit reviews one of the questions is "What is your evaluation
of the documentation?".  Either the reviewers feel that the
documentation is good enough, or they feel that on balance the
library's good points outweigh the poor documentation.

I encourage you to take part in reviews.

To those who have replied to Florian calling him a "leach" etc:
Don't Shoot The Messenger.


Regards, Phil.





_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
On Fri, 2017-09-08 at 16:23 +0100, Phil Endecott via Boost wrote:

> Florian Lindner wrote:
> >
> > why is the documentation so bad?
> The fundamental answer to your question is that Boost libraries
> are subject to peer review, and in the standard invitation to
> submit reviews one of the questions is "What is your evaluation
> of the documentation?".  Either the reviewers feel that the
> documentation is good enough, or they feel that on balance the
> library's good points outweigh the poor documentation.
>
> I encourage you to take part in reviews.

Yes, and there is a review happening right now for the Fit library.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
> Gesendet: Freitag, 08. September 2017 um 04:21 Uhr
> Von: "Florian Lindner via Boost" <[hidden email]>
> An: [hidden email]
> Cc: "Florian Lindner" <[hidden email]>
> Betreff: [boost] Why is the boost documentation so bad?
>
> Hello,
>
> I really love to use boost libraries in my project, but I always wonder, for such an accomplished project, why is the
> documentation so bad?
>
> A few examples:
>
> I want to get familiar with http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/. What do I need to include? Neiter
> the tutorial, the reference or the usage guidelines mention a #include line. This is something which stroke me quite
> often at various boost libs.
>
> Also with the ptr_container lib, I want to find the refrence for the ptr_vector::insert function. I got to scan the
> reference pages of all members of it's class hierarchy to find the insert() function (it's in ptr_sequence_adapter).
>
> References and example code often have no syntax highlightning and no linking and it's extremely hard to find
> documentation for a specific symbol, or from there, to jump to the source code.
>
> I would really like to have a more uniform and a documentation that not feels like a annotated source code dump.
>
> I use doxygen for my own projects and I know it can generate nicely looking, with syntax highlightning and linked
> documentation.
>
> Please, don't take this offensive, it's just some feedback I wanted to give a long time.

I guess most people get used to the documentation after a certain learning curve.
Also maybe the software which generates the documentation could be improved to generate better docs.

I often also find Boris Schälings site on boost helpful:
https://theboostcpplibraries.com/boost.pointer_container

This is kind of what is missing in the Documentation for boost.

thanks,

Jens Weller

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why is the boost documentation so bad?

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 9/7/2017 10:21 PM, Florian Lindner via Boost wrote:

> Hello,
>
> I really love to use boost libraries in my project, but I always wonder, for such an accomplished project, why is the
> documentation so bad?
>
> A few examples:
>
> I want to get familiar with http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/. What do I need to include? Neiter
> the tutorial, the reference or the usage guidelines mention a #include line. This is something which stroke me quite
> often at various boost libs.
>
> Also with the ptr_container lib, I want to find the refrence for the ptr_vector::insert function. I got to scan the
> reference pages of all members of it's class hierarchy to find the insert() function (it's in ptr_sequence_adapter).
>
> References and example code often have no syntax highlightning and no linking and it's extremely hard to find
> documentation for a specific symbol, or from there, to jump to the source code.
>
> I would really like to have a more uniform and a documentation that not feels like a annotated source code dump.
>
> I use doxygen for my own projects and I know it can generate nicely looking, with syntax highlightning and linked
> documentation.
>
> Please, don't take this offensive, it's just some feedback I wanted to give a long time.

Feel free to open an issue for any library's documentation you feel
inadequate.

I completely agree with you that every library needs to specify these 3
things near the beginning of the docs:

1) Level of c++ supported if it is anything above c++03.
2) Header files needed
3) Namespaces used

with optionally:

4) Build instructions for non header-only libraries

Furthermore I believe that some Boost documentation suffers from the
syndrome that library authors believe that adequate docs mean
examples/tutorial + reference, without having to provide any general
explanation and discussion of the actual concepts of the library. But
obviously most Boost libraries are first rate in explaining themselves
and it is very hard to change the mindset of those few library authors
who do not want to explain their libraries in a more expansive manner.

>
> Best,
> Florian


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost