Technical writing is nonfictional content about a scientific field that was written primarily to inform and educate users. A fundamental theory in technical writing is that it should be [[Docs Like Code (lit)|treated like code]]. Below are more concrete principles to keep in mind when setting up a technical writing practice. ## Principles of technical writing ### Answer end users' questions #### Define the different [[Know your audience|personas]] - Users - Administrators - Developers Each group of end users will have different questions and needs, so make sure you have content addressed to each group. #### Identify common questions - What is this product? - Why should I want it? - How does it fit into a broader ecosystem? - What are its prerequisites? - Where/how can I acquire this product? - How do I install it? - What are its basic configuration options? - What does a single end-to-end use case look like? (Happy path) #### Make your content searchable Adding something like [[Algolia]] will help different types of users find the documentation addressing their needs. ### Develop documentation the way you develop code #### Write iteratively [[Agile]] and other methodologies used to plan and build code are also useful for planning and building documentation: - Working in [[Sprint]] - The preference for building small, bite-sized chunks that have production impact #### Set up a process for reviewing and collaboration Most development teams already have a thorough process of reviewing code before releasing it; documentation also benefits from being coupled to this process. - Defects should be logged against documentation, and when one is fixed, the commit message should reference that bug to aid the reviewer. #### Modularize content Don't duplicate content. Create [[Principle of Atomicity]] notes and link them. That way, you'll only need to update documentation in one spot. Some markup languages also use conditional text ([[AsciiDoc]] and [[reStructuredText|RST]]) that let you show parts of articles when certain conditions are fulfilled. ### [[Store content in the same repository as code]] ### Write continuously Continuous integration should involve continuous writing. The same CI/CD tools that build code can be used to build documentation, so that they are published automatically. The lack of manual intervention encourages others to contribute to docs. #### Automate Automate the steps required to publish something, including submission and review processes. It should be easy to change and add things to documentation, so that you (and others) can do it whenever you have an idea. Treat documentation like a working draft that is constantly revised and improved. #### Publish frequently Publishing isn't a special occasion. Frequent publishing allows [[Continuous Improvement]] of documentation. #### Notify others when docs change Webhooks used to integrate GitHub with other team tools like Slack and email can be used for docs as well, informing the team about documentation releases and changes as well. ### Make static websites Pay attention to the "front-end" of technical documentation, as well as the content itself. #### Write content in a lightweight [[Markup languages|markup language]] Keeping content in plain text files reduces the barrier to entry. #### Use a [[Static site generator]] to generate the XML from the content files Storing the documentation on static websites using a [[Static site generator|generator]] reduces the resources, and therefore cost, needed to provision web servers. ### Track documentation metrics Add analytics to your documentation pages to determine which pages are doing the best, which aren't doing too well, and other insights into users' behaviors that might give you a clue as to how best to improve. ## Properties of good technical writing ### Use the right jargon Don't use any marketing jargon at all. People don't want to be sold a product when they're trying to figure out how to get something done. Choose the jargon appropriate for the target audience. ### Avoid long blocks of text Uninterrupted prose is tedious to read. Prefer to use, whenever possible: - lists, numbered and bulleted - tables - diagrams or screenshots - headers ## Formatting - **bold** for UI elements - _italics_ for emphasis - `monospace` for code, commands, and filepaths. ## References - [[Modern Technical Writing]] and [[Modern Technical Writing (lit)|related literature notes]] - Gentle, A. (2018). _Docs like code_. Lulu.com. [[Docs Like Code|Highlights]] and [[Docs Like Code (lit)|literature notes]].