Writing Docs with Visuals and Verve

By Peter Turcan on

Oct 15, 2025

In a past life I worked in the computer journalism business, and learnt over time what attracts people to read a page. Lot’s of things are important, the font used, the spacing between letters and lines and paragraphs, even the width of a column of text is super-important for readability (so the eye does not lose track of the line it is on). Other stuff is important to, readers, especially technical readers, love tables. A table of all the networking libraries available in Boost for example, becomes a reassuring point of reference, as opposed to a bunch of text listing the libraries. Two of the most important factors in drawing readers in are headlines and images. It can take some grey matter and experience and skill to come up with a catchy headline (“Phew - what a scorcher” - is a famous example of a tabloid headline after a super hot day!). The more I worked in journalism the more I appreciated all the skills involved - and those I had and those I had not! When it comes to images, I decided to add at least one image to all the Scenarios in the Boost User Guide (Finance, Networking, Simulation, among others). One of the skills I do not have is that of an artist - so these images mostly had to come from elsewhere. Not all though, for the deformation example in the Simulation scenario, I came up with the following image - which works I guess!

For other images I used AI to come up with some text based diagrams, which do work well as “images” for a technical readership. For example, the following simple flow for a Message Queue shows what is going on, Receiver 3 picking up all the inappropriately addressed messages, as well as its own.

Other images required some research. I must admit I did not know the difference between a petal and a sepal until I did some research on the iris data used in the Machine Learning scenario. The following image is a composite of a picture taken by my wife of an iris in a New Mexico volcanic caldera, and a diagram generated by AI. Now I know, the sepals are the dangly bits I would have called petals before engaging in this research.

Hopefully these images will draw in readers and entice them to try out the scenarios, and then continue their programming journey with the support of Boost libraries.

Another topic I dug into this quarter is to find examples of good and bad practices, and then to tabularize them (remember, tables are trusted references…). I started with error messages. Here is an example of a tedious error message:

error C2679: binary '=': no operator found which takes a right-hand operand of type 'boost::gregorian::date' (or there is no acceptable conversion)

Why is it tedious? Because it is verbose and yet still doesn’t say what the user did wrong, not even the library name is in the message. A shorter, sharper and more helpful message would be:

boost::date_time::invalid_date: "2025-02-30" is not a valid Gregorian date

This message contains the library name (date_time), and the invalid input. Error message content should be a high-priority issue for API developers.

Another topic added to Best Practices is simply API design itself. The Boost filesystem library contains some good examples of clear design, for example - here is a section from the Contributor Guide:

Of course there is an element of style, taste, personal preferences in all these issues. It is totally OK for APIs to reflect those traits of the developers, this guide is there as a check point - a resource to read over and reflect on when evaluating your own work.

Talking of AI - and who isn’t? - I requested the Cpp Alliance give me an image-creating AI API account, so I could add a section to the AI Client scenario on creating images. It is a lot of fun asking an AI to create an image, though you would be correct in thinking you probably could have come up with better yourself! For example, check out this exchange:

Enter your request (ASCII diagram or text) or 'exit': Can you draw an ASCII diagram of a speedboat?

Assistant Response: Sure! Here's a simple ASCII representation of a speedboat:

        __/__
  _____/_____|_____
  \              /
~~~~~~~~~~~~~~~~~~~~~

On a tad more serious note, I added topics on Reflection and Diagnostics to the User Guide. And I scan the Slack conversations for words or phrases that are new to me, and add them to the User Guide Glossary - which is a fun document on its own account. Even a document as potentially dull as a glossary can be fun to create and fun to read. Everybody likes to be entertained when they are reading, it takes the grind out of the experience.