For too long, software documentation has been an afterthought.
We've all encountered software documentation that feels more like a last-minute addition rather than an integral part of the design process. It's no surprise, really. Crafting quality documentation requires skill, time, and a knack for writing. From high-level overviews to how-to guides and references, keeping everything updated can be a daunting task.
But what if I told that ChatGPT makes documentation work easier and more enjoyable; I think this is bound to transform software engineering.
Write documentation for the user
On the ladder of language, writing documentation is moving up from the code level to a more human level.
Documentation should anticipate questions and explain concepts clearly. GPT4 in particular is able to reason well enough to write documentation useful to the user. I ask it to skip over explaining the inner workings and instead to be exhaustive yet concise. A typical prompt might be, "Create documentation that guides a new developer on using the code, highlighting edge cases and crucial details."
Always consider your audience when crafting documentation. Then, ask ChatGPT to tailor your content to meet the reader's needs.
Targeting the different types of documentation
ChatGPT is a versatile tool that can help you create various types of documentation. Here's 4 ways how:
For tutorials and how-tos, merge existing documentation, third-party library documentation, and your shell history. Ask ChatGPT to create step-by-step guides for common operations in your codebase.
For reference material, prompt ChatGPT to produce documentation in a structured format like JSON. Repeat this for each section to ensure consistency. This also makes it easy to index and render the documentation for your website.
Use a diff and commit history to craft a compelling pull request description. You'd be surprised at how much ChatGPT can infer from a few diff lines.
When working with existing documentation and actual code, ask ChatGPT to write accompanying examples. Direct examples often prove to be the most useful part of documentation.
So, why wait? It's time to transform your documentation into something actually your colleagues actually enjoy reading!