This week I have taken a look at Bob Ducharme, a senior technical writer at Ontotext, a company that produces data management software, and his personal blog. In this entry, Ducharme details various points surrounding the importance of documentation standards, or guidelines for efficient documentation, and provides a brief dive into documenting Application Programming Interfaces. His main stance on documentation is that it should always align with the specific company’s product vision, this is to ensure that user ease is prioritized especially when it comes to understanding a product, as good documentation can be a great form of marketing. Ducharme then provides tools and tips for documentation, Jupyter Notebook is recommended as well as keeping things short, readable, and proportional, especially code samples. He also warns to avoid documentation presented in multiple top-level sections. This is a common practice amongst companies nowadays but it makes for a more difficult navigation experience for users. Ducharme then went on to write about the documentation of APIs. His top points were that documentation is critical when working with some programming languages due to their functions and libraries that lend insight into a product’s internal workings. He provides more advice for documentation tools as he recommends Swagger, Sphinx, Pydoc, and Doxygen because they can take the comments found in the code and turn them into formatted documentation with the aid of a tech writer clarifying the necessary parameters needed for documentation standards to be met. 

I selected this particular post for many reasons, the first and main reason being that I always appreciate when an author creates a sense of personalness. I find a piece more readable and attention-grasping when it avoids a strict formal tone and has a story-like quality. Ducharme even included a hand-drawn diagram that really added that personal touch. To add to the readability factor, Ducharme formatted his post into bulleted sections, breaking things up more concisely and providing an easier and more engaging read. I also could immediately trust the information I was reading as within the first paragraph Ducharme lies down a line of credibility by mentioning he is an accredited enough figure that he has been asked to be interviewed on podcasts to speak on this specific topic. He is also a senior writer in the field, providing his own experiences from his career. Another huge factor is all of the great advice provided about proper documentation standards and the inclusion of different resources to reach efficient documentation.

I feel Ducharme supplied really important advice on documentation standards that I will take with me into the future and apply myself. I have clear sense of what makes efficient documentation and that complex sectioning is not always necessary and keeping things user-orientated, thus simple and readable is the route to go. Ducharme gave a very thorough description of documenting API, allowing his expertise on that topic to shine through. His explanation was very educational and I definitely see myself using Swagger, Sphinx, Pydoc, or Doxygen for assistance in formatting comments properly. Also in future practice in my career space if working as a developer I will know how to properly work with tech writers who are trying to achieve documentation standards. For example, when providing a type of parameter I will be sure to indicate what the typical high and low values will be and the effects they will have so the tech writer can make the necessary correct alterations. Overall, if looking for a refreshing insight into achieving documentation standards with the inclusion of the best formatting standards and helpful tools to achieve them I would highly recommend giving Bob Ducharme’s blog a read ( https://www.bobdc.com/blog/techwritingadvice/ ).

From the blog CS@Worcester – CS Journal by Alivia Glynn and used with permission of the author. All other rights reserved by the author.