CppCon 2017: Robert Ramey “How to Write Effective Documentation for C++ Libraries...”

How to Write Effective Documentation for C++ Libraries with Minimal Effort

—
—
With the success of GitHub, everybody and his brother is a library developer. Programmers love to create code, upload it to GitHub and hope for immortality. Most projects get only the most cursory examination before being passed over by users. Why is that? GitHub considered the problem.

Even the most experienced and dedicated software developers can't do it. This can be confirmed by looking over recent reviews of Boost libraries. The most common complaint is that the documentation isn't useable.

Programmers love their stuff and hope to get people to use it, why don't they fix their documentation? The reason is simple: They don't know how.

Problems

a) It's tedious and boring to write
b) Developers don't know what to include and what to exclude
c) Tools make things harder
d) Regardless of the amount of effort invested, the end result is usually of little or no value.

This presentation will present a "Cookbook" and demonstration for creating documentation. Using this method will

a) Much diminish the tedium of the task.
b) Help improve to the quality of library design and implementation
c) Create something that is useful to the library user.

We will touch upon tools like Doxygen, etc. But this is only a small portion of the presentation. We use them so they deserve mention. But they don't cause the problem, and they don't solve it either.
—
Robert Ramey: Robert Ramey Software Development, Proprietor

—
*--*
*-----*

[jaredmulconry]

I found this talk quite informative. As a young developer, I am still establishing what makes for good development practice in what context.
Documentation is something I struggle with as I've always seen it as a burden.
The thing that this talk showed me is that documenting the wrong thing is a burden.

Thanks, Robert!

[hmpcon]

This was a surprisingly good talk. Important reminder of the importance of technical writing skills as a cornerstone of being a well-rounded engineer.

[robertramey]

I noticed that I talked about what to document and didn't really talk about how to write. For good reason - I'm not really a great writer. If you want to improve your writing skills at writing documentation and simplify your life, task a look at

[robertramey]

note that you can download the (corrected) slides at my website www.rrsd.com

[tijshoeijmakers]

Thank you Robert. Interesting talk!

At some points the audience is trying too hard to be smart which I find quite annoying and not of so much value.

[init]

Thank you Mr. Robert, this is exactly what I was looking for! Stellar presentation and talk

[kamalabuhenamostafa]

A teacher should not believe anything but proof. AND the subject have proofs.