Boost docs

From: Peter Turcan (peterturcan_at_[hidden])
Date: 2023-04-11 19:47:26

Hi,

This week I joined CppAlliance as a technical writer - just introducing
myself here!

I am pumped to be writing some C++ code after several years hiatus. The
last major project I wrote in C++ was a wargame that would cope with battle
data from either the Napoleonic wars, or the American Civil War, and was
called Battalia. It is still around in archive sites such as:

https://archive.org/details/wargamer-depot_battalia

Mostly I write developer documentation and tutorials. The work I enjoyed
the most was writing the SDK for Microsoft Flight Simulator (and taught
myself instrument flying in the process), the User Guides and SDK for
WorldWide Telescope (an astronomy viewing program that involved working
with NASA on Mars imagery data), and writing a range of developer tutorials
for Azure IoT, Azure Search and Azure Maps. I was the main writer at
Microsoft for the DirectX 12 documentation - though that was a brutally
tough SDK to actually work with. Most developers stuck with DirectX 11 -
not sure where Microsoft is now on its graphics APIs.

At CppAlliance I hope to add value to the documentation on the libraries
where I can - perhaps adding examples, better navigation, and more complete
descriptions of parameters, edge-cases, errors - the usual suspects that
are often missing from documentation but are sorely needed by developers.

Also, I plan on getting hardcore with the introductions to each library.

The question that should be answered in introductions to any library (or
any SDK) is the "why" question. Why should I be interested in this library?
What is the problem that I have that the library is solving? This is often
missing. A typical introduction might answer the "What" question - such as
"this particular piece of software converts A into B", and the "How"
question (what tools and setup is needed), but avoids the why question:
"why should I be interested in converting A into B". The answer might be:
"this library converts A into B to provide your data with an additional
level of security, when the data is communicated over the internet." By
answering the why question, any developer will know immediately whether to
continue reading, or look elsewhere.

Another aspect of documentation to look at is style. For API reference type
documentation (interfaces, functions, parameters), mostly a neutral style
works well - just say exactly what is going on. For guide or more
conceptual material, perhaps a chattier style is more appropriate - short
sharp sentences, some wit and wisdom, less formality - like talking to a
knowledgeable buddy.

You probably have some great ideas too on adding value to the existing
Boost documentation - happy to hear any and all feedback!

- best
Peter