Have you registered for CppCon 2018 in September? Registration is open now.

While we wait for this year’s event, we’re featuring videos of some of the 100+ talks from CppCon 2017 for you to enjoy. Here is today’s feature:

How to Write Effective Documentation for C++ Libraries...

by Robert Ramey

(watch on YouTube) (watch on Channel 9)

Summary of the talk:

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.

GitHub just published its 2017 Open Source Survey. The popular social coding service surveyed over 5,500 members of its community, from over 3,800 projects on github.com. It also spoke to 500 coders working on projects from outside the GitHub ecosystem. The Open Source Survey asked a broad array of questions. One that caught my eye was about problems people encounter when working with, or contributing to, open source projects. An incredible 93 percent of people reported being frustrated with “incomplete or confusing documentation”. see https://thenextweb.com/dd/2017/06/02/...

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.