Technical Writing for Software Developers  🔗 **Source:** [Technical Writing for Software Developers]() ## Highlights - Technical writing is any media, mostly words, but not always, that explains to someone how something works and how they can use it. ([Location 255](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=255)) - Note: Not marketing, copy editing, or, blogging - Tags: aqua - This book is mostly aimed at developers who want to learn how to explain their creations to the world better. ([Location 274](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=274)) - Tags: aqua - Much like the terms developers, engineers, and programmers, practitioners in this field also refer to themselves in ways that are mostly the same but mean different things to those who use them. The two main terms you have likely heard used interchangeably are “technical writing(er)” and “documentation”, plus maybe some other terms appended. ([Location 279](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=279)) - Tags: aqua - a “product” is something commercial, whereas a “project” might not be. ([Location 293](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=293)) - Tags: aqua - Documentation gives confidence in a product making it useful for marketing sales enablement, customer support, search engine optimization (SEO), and, as we now realize, for myriad other machine-driven purposes. ([Location 391](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=391)) - Tags: aqua - Good documentation brings confidence in a product to a potential customer or user. ([Location 407](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=407)) - Tags: aqua - Customer success, support, or whatever a company calls the team of people who help users achieve their goals are often any documentation team’s biggest allies and sources of knowledge. ([Location 414](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=414)) - Tags: aqua - regularly syncing with them gives you a great source of information for what documentation is missing and how effective current documentation is. ([Location 417](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=417)) - Tags: aqua - Though they are often part of sales or marketing teams, developer relations teams are typically out speaking with developers, convincing them, and helping them use a product. The content they produce could be one of the first things that a potential user sees, so again, work with them to ensure consistency of message, reduce silos, and much like support, find out what they feel is missing from the documentation that would help users. ([Location 419](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=419)) - Tags: aqua - “Documentation makes engineering look good.” ([Location 425](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=425)) - Tags: aqua - the reality of the documentarian role is that you often don’t feel as important as everyone says you are. ([Location 469](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=469)) - Tags: aqua - while gathering and processing so much information can be overwhelming, it is also rewarding. Documentarians are often the first testers of a new product or feature, the first to find issues, and the first to follow a user workflow outside of a development team. ([Location 474](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=474)) - Tags: aqua - Who is reading a document? What do they want to accomplish? Why do they want to accomplish it? ([Location 485](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=485)) - Tags: aqua - Most inexperienced users start their journey with you via a Getting Started guide or onboarding experience. ([Location 566](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=566)) - Tags: aqua - Onboarding is sometimes called a tour or in-app help and is typically part of an app or product experience. ([Location 568](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=568)) - Tags: aqua - Documentarians are a key part of developer experience (DX), a growing movement of practices and professionals that focus on making developers’ technical lives as frictionless as possible. ([Location 577](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=577)) - Tags: aqua - time to first hello world or time to Getting Started. ([Location 580](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=580)) - Tags: aqua - highlight what makes your product great and why someone should use it ([Location 606](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=606)) - Tags: aqua - follow an opinionated path that showcases the first point but can offer links to where to find alternative paths and more information ([Location 607](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=607)) - Tags: aqua - Templates for a Getting Started guide Ideally, a Getting Started guide should have content under the following headings: Overview: What the reader can expect from the guide. Prerequisites: What steps the reader needs to take before starting the guide. Installation: How to install any components that are needed. Setup: How to set up the components that are needed. Parts: A series of tasks that form the guide. These are individual headings that should actively describe what the reader will learn and accomplish: Steps: Each step is under the task. These are individual headings that should actively describe what the reader will learn and accomplish. Summary: What did the reader learn in this guide, and why is it useful and relevant? Next steps: Where to go next to build upon the knowledge learned. ([Location 610](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=610)) - Tags: aqua - Every inconsistency you have leaves the reader wondering if you mean the same thing as you meant before. ([Location 952](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=952)) - Tags: aqua - with technical documentation, you should use active voice as much as possible. ([Location 981](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=981)) - Tags: aqua - Passive voice can obscure details and make it unclear what is happening with what effect. ([Location 982](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=982)) - Tags: aqua - “Verbs come in two types, active and passive. With an active verb, the subject of the sentence is doing something. With a passive verb, something is being done to the sentence’s subject. The subject is just letting it happen. You should avoid the passive tense.” ([Location 988](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=988)) - Tags: aqua - Using passive voice can make you sound less responsible for something. ([Location 994](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=994)) - Tags: aqua - Rarely needed in technical writing, “very” does nothing but accentuate something you have already said. ([Location 1048](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1048)) - Tags: aqua - A verb is a word that describes an action, state, or something that happened. It’s often the main part of a sentence. For example, in “The function returns value x,” the verb is “returns.” ([Location 1055](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1055)) - Tags: aqua - A noun is a person, place, or thing. For example, “function” is a noun. ([Location 1057](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1057)) - Tags: aqua - An adjective is a word that describes a noun, for example, a “complex function.” ([Location 1058](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1058)) - Tags: aqua - An adverb is a word or phrase that modifies or adds to an adjective or verb, for example, a “very complex function.” ([Location 1059](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1059)) - Tags: aqua - “With adverbs, the writer usually tells us they aren’t expressing themselves clearly, that they are not getting the point or the picture across.” ([Location 1068](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1068)) - Tags: aqua - You don’t need to repeat something you just said to make a point. ([Location 1100](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1100)) - Tags: aqua - Another less obvious use of negative language to avoid is when describing what the reader can and can’t do with what you’re documenting. ([Location 1116](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1116)) - Tags: aqua - when referring to individuals, there has traditionally been a difference of opinion between US and non-US English on this topic. Typically, in non-US English, you can use “they/them” almost anywhere to avoid using gender when referring to an animate actor. Traditionally, this was grammatically incorrect as it’s supposed to refer to a group of people, but being the flexible language it is, English has grown to accept this as correct. ([Location 1135](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1135)) - Tags: aqua - “The service operates like a middleman, passing status messages to other services.” You should replace “middleman” with something without a gender, for example, “intermediary.” ([Location 1145](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1145)) - Tags: aqua - instead of “Disable the configuration option,” it’s better to use toggle, turn off, change, and so on, depending on the use case. ([Location 1155](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1155)) - Tags: aqua - Remove as much of their cognitive load as possible when trying to understand complex or new topics Give the reader confidence that what they are reading is the best practice around a product and that the product can help them accomplish their goals Make it as clear as possible to readers how to accomplish a task they want to understand Make language as inclusive and unbiased as possible to broaden your audience and make them feel welcome ([Location 1175](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1175)) - Tags: aqua - Have you ever attempted to read and understand something complex to be faced with a solid wall of text that’s hard to parse to the point where your eyes stop processing any potentially fantastic information? Crafting the perfect words is a waste of time if you make it extremely hard for anyone to read them. ([Location 1185](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1185)) - Tags: aqua - Humans are not your only readers The principles of good layout A primer on markup languages for the web Thinking about pages semantically Creating documentation menus and navigation ([Location 1191](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1191)) - Tags: aqua - Break up paragraphs as much as possible by a group of topics or a few sentences at a time. Don’t fear whitespace. ([Location 1253](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1253)) - Tags: aqua - subheadings. They break up the wall of text and draw people’s eyes to important information. ([Location 1255](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1255)) - Tags: aqua - While bullet points and numerical lists can help break up walls of text, don’t overuse them or feel that all paragraphs should be short. This is a trend that’s quite popular now. Especially in clickbait blogs. ([Location 1282](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1282)) - Tags: aqua - “admonitions” (my preferred term), “alerts,” or “callouts.” One non-agreed term for the same thing. A small, marked area of text denotes additional information relevant to the current topic. Depending on the tool, you can typically denote an admonition as one of the following types, which results in the following formatting: Info: Additional information that could interest the reader but isn’t essential to know, such as background details or history. Different tools render this in different colors, typically gray or blue. Note: Note and information might sound similar, but they are more for supplemental information that is useful to some people in some situations – for example, if you use a network proxy, an unusual processor architecture, and so on. Different tools render this in different colors, typically gray or blue. Tip: Information that could be useful to most people but not essential. An example could be updating dependencies before installing one specific to the project. It’s typically rendered in green. Caution or warning: Information that’s somewhat important for most people to see – for example, to ensure the reader is connected to the right network before issuing a command. It’s typically rendered in yellow or orange. Error or danger: Information that’s essential for people to notice and read – for example, not reading could cause data loss, high costs, and so on. It’s typically rendered in red. ([Location 1305](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1305)) - Tags: aqua - Your content needs to be readable as well as well-written There are many more readers of your documentation in addition to human eyes ([Location 1427](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1427)) - Tags: aqua - Scoping and requirements gathering Research and product testing Drafting and re-drafting Feedback, testing, and maintenance ([Location 1439](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1439)) - Tags: aqua - Within a company or project, documentation requests can come from a variety of internal and external sources, including the following: A new feature that’s in progress, probably from a product owner A new feature that’s already been completed that needs documentation A feature gap that’s been identified by you or others A content gap that’s been identified by you or others A problem that’s been logged by you or others ([Location 1444](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1444)) - Tags: aqua - My general advice is to start at the beginning, then the end, and slowly fill in the gaps in the middle over time based on feedback. This means creating a getting started guide or two and then ensuring that reference documentation is available to cover resources such as API or SDK functions. With these in place, you can release “minimum viable documentation.” The getting started guides will be enough for those who are interested in experimenting with a product to see if it suits their needs, and the reference documentation will be enough for those who know what they want to accomplish and need more details on the individual components to use. ([Location 1485](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1485)) - Tags: aqua - what documentarians do have is a broad overview of many things, sometimes more than anyone else. It’s the nature of creating documentation. You need to know how components fit together to form a flow, even if you’re a writer on a team. ([Location 1502](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1502)) - Tags: aqua - Here are some potential questions to ask: What did you think about what you read? If you could change anything about what you read, what would it be? What was easy or difficult to understand and why? How would you explain this content to someone else? Does this address your needs? If not, why not? ([Location 1556](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1556)) - Tags: aqua - Your job is to sift through all that feedback and determine what you want to act on and when. As a documentarian, you may not be the expert on the product’s inner workings, but you are an expert on figuring out how to explain them. It’s OK to push back on feedback, but do it in a friendly, professional manner and explain why you choose not to accept it. ([Location 1573](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1573)) - Tags: aqua - when is a feedback round complete so that you can publish changes to the documentation? This can depend on your work sector and the risk of incorrect documentation. ([Location 1584](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1584)) - Tags: aqua - one person’s feedback from a silent majority of thousands of users may not be worth addressing. If, however, multiple users give the same or closely related feedback, it’s worth addressing. ([Location 1621](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1621)) - Tags: aqua - Opinions and feedback aren’t always the same thing. Again, you need to assess the number of people who have given the same or closely related feedback, but remember that someone thinking something is wrong doesn’t mean it is. ([Location 1622](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1622)) - Tags: aqua - Internal roadmaps, priorities, and agendas can trump external feedback and requests. This doesn’t mean that you ignore the external input, but it does mean you need to communicate this fact with the feedback giver. ([Location 1624](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1624)) - Tags: aqua - popular metric to track is something along the lines of “time to get started.” ([Location 1642](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1642)) - Tags: aqua - Another good metric to try and track is how changes in documentation affect interactions with support. Drawing direct correlations is difficult, and measuring this is a mix of quantitative and qualitative metrics, but over time, you can probably start to see when the quantities of questions relating to certain topics change. ([Location 1646](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1646)) - Tags: aqua - decide on the kinds of aspects of the content you should maintain. Here are some ideas: Any changes to the company or project style guide since the page was last updated (more on this topic later) Software and dependency version updates mentioned in the content Follow any technical flows to see if they still work as intended Render errors in the live version of a page Screenshot updates for any output changes from the application or project ([Location 1654](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1654)) - Tags: aqua - Writing Collaborating Managing and rendering Analyzing and assessing ([Location 1681](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1681)) - Tags: aqua - However, engineers might still read the documentation in print in some risk-averse industries. The three main methodologies are as follows: Topic-based: Conforms to industry-wide standards with specific specialized tooling. Docs as code: Uses traditional developer workflows and tooling. This is the main focus of this chapter. Browser-based: Uses tools and services in the browser. ([Location 1686](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1686)) - Tags: aqua - Docs as code aims to follow principles for documentation similar to those of developers. This includes using markup languages in plain text files in a text editor to write, version control to manage collaboration, testing, continuous processes, and more. ([Location 1761](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1761)) - Tags: aqua - GitBook (https://www.gitbook.com): A hybrid of docs as code and browser-based, GitBook attempts to combine many of the positives of both into a tool that satisfies team members with different experiences and knowledge levels. Confluence from Atlassian (https://www.atlassian.com/software/confluence): If you use other Atlassian tools, you may also have access to Confluence. While it’s primarily designed for internal documentation, you can also use it for externally-facing content. I never found it the most optimal option for technical documentation, but with a large ecosystem of plugins and integrations, it’s a flexible and widely used option. Knowledge Owl (https://www.knowledgeowl.com): Aimed at less technical products and businesses but nonetheless popular with an enthusiastic customer base, Knowledge Owl focuses on “knowledge base”-style documentation resources. Paligo (https://paligo.net): Full of features for the entire content workflow, from planning to publication, Paligo also offers multiple integration options to keep developers and developers’ managers happy. ([Location 1780](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1780)) - Tags: aqua - The key factors to consider in any tools section process are as follows: What is your current team’s experience? What are they comfortable using, what have they used before, and what do they want to use? How standard is what you’re considering? This relates closely to the last point, but it’s important to consider what happens when a team changes. If you use something less common or specialized, it could be hard to replace team members. What’s your budget? I love open source and rolling my own tooling, but it’s an easy trap to think that means the tooling is “free.” With paid options, you offload development and maintenance work to someone else’s team. But when you’re creating your own tooling, your team has to set up and maintain it. That takes time, probably more time than you think, and also has a potential inherent cost, as it’s time they aren’t spending on doing their core work. What do you need? You might think this is the most important point on this list, but I would argue otherwise. While the overall methodology you choose makes a reasonable difference, once you get down to the level of individual tool choice, it becomes less important, as most tools have most features. In the end, decisions usually come down to the first three points. ([Location 1798](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1798)) - Tags: aqua - This is where MDX comes in. It allows you to mix Markdown with components, often React components, but not exclusively. This means you can add all sorts of frontend elements to the Markdown, including some of the documentation-specific formatting options I mentioned in Chapter 4, plus many others, including those you use in your actual frontend applications. ([Location 1912](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=1912)) - Tags: aqua - Decide on a consistent example. Create and organize code examples. Test code examples. ([Location 2147](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=2147)) - Tags: aqua - If you want to take accessibility a step further, remember my point about images and text complimenting each other. An image added with little context in the text around it may give enough information to someone who can see it, but with no context around an image, even good alt attribute text gives little help to someone who can’t see the image. ([Location 2346](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=2346)) - Tags: aqua - A style guide is a combination of things, and while many writers have encountered them, developers might be less familiar with them. Think of a style guide as comparable to something such as a configuration file for defining rules for JavaScript code with ESLint (https://eslint.org) or Rust with Clippy (https://doc.rust-lang.org/clippy/) but for human language. ([Location 2540](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=2540)) - Tags: aqua - These include the Microsoft Manual of Style (https://learn.microsoft.com/en-us/style-guide/welcome/) and the Google style guide (https://developers.google.com/style/accessibility), ([Location 2557](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=2557)) - Tags: aqua - the Google style guide has a section about not making “excessive claims” (https://developers.google.com/style/excessive-claims). ([Location 2582](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=2582)) - Tags: aqua - Write Good (https://github.com/btford/write-good) checks for several common style and grammar errors that you can toggle and use via JavaScript, a command-line tool, or IDE extensions. ([Location 2606](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=2606)) - Tags: aqua - TextLint (https://textlint.github.io): If you’re familiar with ESLint and the wider JavaScript world, TextLint will feel familiar. After installing the core package, as in the following snippet, for every check you want to add, you install another TextLint package. The following code installs the core package and a rule that checks for any TODO tags left: npm install --save-dev textlint npm install --save-dev textlint-rule-no-todo ([Location 2615](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=2615)) - Tags: aqua - You can build your style guide rules based on existing codified versions of everything from the Microsoft style guide to Write Good to lists of technical jargon words and add your own additions and exceptions. ([Location 2643](https://readwise.io/to_kindle?action=open&asin=B0CYL9SWZ5&location=2643)) - Tags: aqua