Docs for Developers  ## Metadata - Author: [[Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse]] | [[3. Resources/Authors/Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse|Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse]] - Full Title: Docs for Developers - Category: #books - Kindle: [Open in Kindle](https://www.amazon.com/dp/B09HLZGWKT) - Document Tags: [[Dev Work]] ## Document Notes ## Highlights - In the late 1980s, a group of economists at Harvard determined that humans assume others have the same knowledge they do. They named this cognitive bias the “curse of knowledge.” ([Location 579](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=579)) - This chapter guides you through breaking the curse of knowledge and understanding your users by: Identifying the goals you have for your users Understanding who your users are Understanding your users’ needs and how documentation addresses them Condensing your findings into personas, stories, and maps Testing your assumptions with a friction log ([Location 592](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=592)) - Developer skill Programming languages Developer environment Operating system Team role A list of characteristics gives you a starting point for user research. You can add more categories later as your research progresses. ([Location 628](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=628)) - Some questions, in general, apply to all products. Questions like: What is this product? Will this product solve my problem? What features are available? How much does it cost? How do I get started? ([Location 633](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=633)) - Other questions are going to be very specific to your product, your users, and their goal: How do I authenticate against your API? How do I use a specific feature? How do I troubleshoot a specific problem? ([Location 635](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=635)) - Developer relations Product support User experience Marketing ([Location 654](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=654)) - Note Consider the diversity of the people you talk to. Look at the age, gender, disabilities, ethnicity, job duties, and social and economic status of your pool. Are your interview participants representative of the wider group of people who will eventually read your documentation? ([Location 696](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=696)) - Three useful ways of condensing your user research findings are: User personas User stories User journey maps ([Location 725](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=725)) - A user persona is a semi-fictional character created to represent your ideal reader or readers. This character can be based on a specific person or an amalgam of people you learned about in your research. A user persona usually includes a short description of the individual (real or imagined) and a list of their goals, skills, knowledge, and situation. ([Location 727](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=727)) - A friction log is a journal in which you try your software as a user would and record your experiences. To record your experience, log each step sequentially, noting the behavior you expect and the actual behavior of your software. The bigger the gap between expectation and reality, the bigger the opportunity to improve your docs or software. ([Location 781](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=781)) - A use case (also called a business problem or user scenario) is a set of tasks required to complete a goal. Each task is an interaction with your service or systems. You can create use cases from researching your users and finding what goals are most important to them. When you identify the most important use cases for your users, you can plan your documentation with content types that address their needs. Good documentation describes use cases that help your users meet their goals. ([Location 862](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=862)) - A README is a single text file, often written in Markdown, that summarizes a collection of code, usually at the top level of the code repository.2 You can also write READMEs for important subfolders that require additional summary or explanation. A README contains basic information like: What the code does at a high level How to install it Troubleshooting steps Who maintains the code License information A changelog Basic examples Links to more in-depth resources and documentation ([Location 889](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=889)) - As you write a getting started document, some questions you should ask yourself are: What are the quickest explanations of what this service is and what its core features do? What are the simplest steps to install and use your product? What are the most important questions new users will have? What are the cool things they can do with your service? ([Location 907](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=907)) - Procedural content includes tutorials and how-to guides—anything from installation instructions to API integrations. A procedural document shows readers how to accomplish a specific goal by following a set of structured steps. A single step should describe a single action that a user takes. ([Location 937](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=937)) - Links in the middle of your document may distract readers. Instead, provide links to additional resources at the bottom of the page. ([Location 982](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=982)) - Any complex system has terms with unclear meanings. A glossary is a collection of terms and definitions that are specific to your service, field, or industry. ([Location 1007](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1007)) - A changelog provides a helpful historical record for internal teams like support and engineering. ([Location 1036](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1036)) - Release notes are another helpful type of documentation. Release notes provide rich context for the changes listed in a changelog. While a changelog can be automated or consist only of a bulleted list with little context, release notes speak directly to your users. Here's the change that took place. Here's why. Here's how it used to be. Here's how it's going to be. Release notes give users context to understand why a change took place. ([Location 1044](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1044)) - You can start your document by listing the information you’ve already gathered at the top: Audience Purpose Pattern ([Location 1158](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1158)) - A procedure is a sequential set of actions a reader takes to achieve a desired result. Procedures should always use numbered lists to help readers understand the order of tasks they’re performing. Explain the desired goal at the start of the procedure so that users understand what they are doing. At the end of the procedure, add a way for the user to check that they performed it correctly. ([Location 1234](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1234)) - Like code reviews, editing is a collaborative process, where you share your content with others, test your assumptions, and gather feedback. This may feel vulnerable at first, but it’s also where the most learning happens. As you integrate the feedback you receive, you may see more elegant ways to approach the problem you’re documenting and write more effectively. ([Location 1420](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1420)) - When editing for technical accuracy, you’re editing for the correctness of your content. You should be able to answer the following questions: If someone follows these instructions, will they get the result you promised them? Is there any technical jargon or terms that might lead to confusion? Are code functions, parameters, and endpoints named and explained correctly? ([Location 1436](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1436)) - Editing for completeness is a great time to involve a new reader. New readers often see the gaps in your explanations and instructions far more quickly than you do. ([Location 1455](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1455)) - As you edit for structure, you’re trying to answer the following questions: Is it clear from the title and headers what the document is about? Is the document organized in a consistent and logical way? Are there sections in this document that should be put in another document? If a template exists, does the document follow it? ([Location 1465](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1465)) - As you read each section of your document, ask yourself the following: Is this as clear as it can be? Are there terms used inconsistently that I should correct? Are there unnecessary words or phrases that I can cut? Are there any idioms, metaphors, or slang that could confuse readers? Am I using any biased language that should be avoided? ([Location 1485](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1485)) - You may only criticize an idea if you also add a constructive suggestion. ([Location 1558](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1558)) - Constructive suggestions provide additional context for what you think would solve the problem. ([Location 1561](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1561)) - A good code sample should be: Explained: It’s displayed alongside a written description, whether in the main body of text or in code comments to provide context and explanation where needed. Concise: It provides the exact amount of information needed by the reader. Clear: It follows conventions a reader would expect of the language the sample is written in. ([Location 1644](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1644)) - Executable code should also be: Usable (and extensible): It’s clear how the reader uses the sample and where they need to input their own data. Trustworthy: It’s pastable, works, and only does what a reader expects. ([Location 1648](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1648)) - Make sure your samples are: Explained: Provide the why, not the what, behind your sample. Concise: Aim for minimal reproducible examples. Clear: Lean on existing conventions and style guides. Extensible: Make it clear where and how a reader needs to amend their own code. Trustworthy: Be consistent and test, test, and test again. ([Location 1791](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1791)) - Like written documentation, the most effective visual content is something the reader barely notices. It doesn’t require them to stop in order to think or be aware of the fact they are consuming anything at all. ([Location 1851](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1851)) - Ineffective visual content interferes with the transfer of information, usually due to a lack of: Comprehension Accessibility Performance ([Location 1869](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1869)) - If you think a screenshot would be useful to your readers, make sure they: Never appear without introduction or reference in the text. Appear close to the instructions or related text. Are clean and clutter free—do not include anything in your screenshot not part of your UI. Include all relevant parts of the UI with enough context to reassure the reader they’re on the right screen. Not too big—your readers need to be able to read all parts of the image. Not too small—your readers need to be able to correlate the screenshot to the UI they experience. ([Location 1899](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1899)) - There are several types of process diagrams that are particularly helpful in documentation: Boxes and arrows Flowcharts Swimlanes ([Location 1917](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=1917)) - Building a content release process Creating a publishing timeline Finalizing and approving publication Announcing your content to your audience ([Location 2098](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2098)) - Your content release process should answer the following questions: When are you going to publish your content? Who is responsible for final review and publication? Where are you going to publish your content? What additional software tools are needed to publish the content? How will you announce your new content to your users? ([Location 2103](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2103)) - Test your docs, even if they’re not part of your codebase. If you don’t have unit tests for code samples, test instructions manually. ([Location 2140](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2140)) - To meet your users where they are, consider the following questions and scenarios: Are they internal teams looking for the right way to use something in your organization? A private wiki or an intranet site is a good place to put it. Are your readers external users who work with code or endpoints? It’s convenient for them if the documentation is in the same repository as the code. Are your readers end users or system administrators looking to install something? Make sure the documents are external to the software to avoid a dependency loop. Are your readers external users of your codebase? Put it on your website or in your code repository. ([Location 2157](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2157)) - There are many creative ways to gather feedback from your users. For the purposes of this chapter, we focus on these channels that relate closely to documentation: Accepting feedback directly through documentation pages Monitoring support issues Collecting document sentiment Creating user surveys Creating a user council ([Location 2239](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2239)) - Document sentiment is how readers feel about your documentation. You can discover and measure document sentiment through a simple survey or by using embedded code on a page that prompts a user to indicate by clicking a simple yes or no whether the page was helpful ([Location 2268](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2268)) - How satisfied are you with Corg.ly’s documentation?   2. Are you able to find the information you were looking for?   3. How much time did it take you to find this information?   4. Did this effort match your expectations?   5. What can we do to improve our documentation? ([Location 2285](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2285)) - Each feedback issue should be quickly evaluated to see if you can answer the following questions: 1. Is the issue valid?   2. Can it be fixed?   3. How important is the issue?   The following sections dive into each of these questions, defining specific requirements for answers at each step. Answering these questions helps you separate actionable user feedback from feedback that needs more information and feedback that can be ignored. Applying a standard triage process is critical because it:3 Speeds up the response times to user issues Prevents requested work from lingering endlessly Builds a standard set of priorities for issues Directs limited resources toward the most necessary and impactful changes ([Location 2314](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2314)) - For a documentation issue to be actionable, it must be: Original Reproducible Scoped ([Location 2334](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2334)) - If a document is good when it fulfills its purpose, then what is its purpose? The purpose of your documentation should align with the purpose of your code: to drive specific user behavior and accomplish the goals of your organization. ([Location 2424](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2424)) - Functional quality, which describes whether or not a document accomplishes its purpose or goal Structural quality, which describes whether a document is well written and well structured ([Location 2427](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2427)) - The functional quality of documentation can be broken down into the following categories:2 Accessible Purposeful Findable Accurate Complete ([Location 2433](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2433)) - Findability is the measure of how easily your readers navigate to and through your content. ([Location 2472](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2472)) - Accuracy is the measure of how correct and credible the content is in a document. ([Location 2487](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2487)) - A document is complete if it contains all of the information necessary for the reader to succeed. For a task-driven document, completeness means: 1. Listing all prerequisites that readers should follow.   2. Documenting all tasks required to finish the task.   3. Defining next steps the reader should take. ([Location 2495](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2495)) - This book uses the “three Cs” of good writing to define structural quality: Clear Concise Consistent ([Location 2505](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2505)) - clear documentation has: Well-defined and well-ordered headers that break down a topic into logical sections Headers ordered chronologically for tasks and each step indicating the desired outcome Unambiguous results for each step in a process Steps organized in a way your readers understand Content that calls out any places where a reader might get stuck Definitions of any errors that users may encounter ([Location 2508](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2508)) - Organizational goals are specific behaviors the organization wants from its users. ([Location 2552](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2552)) - Recruiting and onboarding new users Encouraging existing users to adopt new features Getting users to complete a specific task Retaining existing users Addressing users’ support needs and product questions ([Location 2555](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2555)) - Documentation metrics you can collect include: Unique visitors: Unique visitors are the number of people who have visited your site over a set period of time. Page views: A page view records each time a visitor looks at a page. Page views help you understand which of your pages are visited most, least, or not at all. Time on page: Time on page tracks the amount of time a visitor spends on your page before moving on to the next one. Bounce rate: Bounce rate is the number of visitors who come to your site, visit one page, and then leave (“bounce”) without viewing other pages. Search keyword analysis: Keyword analysis shows you the search terms visitors use to enter your site. It can help you understand whether you’re providing the information your users are looking for. Reading level or text complexity analysis: Reading level or text complexity analysis helps you understand how difficult your pages are to read and understand. Support issues related to documentation: Tracking support issues related to documentation helps you understand where documentation fails to meet your user’s needs. Link validation: Link validation evaluates whether links to and from pages on your site are broken. Broken links are a common source of user frustration. Time to Hello World (TTHW): Time to Hello World is the amount of time it takes a developer to author “Hello World” in a new programming language or to accomplish a fairly simple task with your service. ([Location 2589](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2589)) - When evaluating the quality of your content with documentation metrics, keep the following tips in mind: Make a plan Establish a baseline Consider context Use clusters of metrics Mix qualitative and quantitative feedback ([Location 2618](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2618)) - Why do you want to measure? What will you do with the information? How will your effort advance the goals of your organization? ([Location 2624](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2624)) - baseline allows you to compare metrics before and after you’ve made changes so you can evaluate their impact. ([Location 2628](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2628)) - Planning your information architecture, and helping your readers build a mental model of your content means incorporating new elements into your set of documentation, including: Site navigation and organization Landing pages Navigation cues ([Location 2728](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2728)) - Landing pages are pages that route users to the right content with minimal reading required, building trust with users by saving them time. ([Location 2769](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2769)) - Navigation cues include elements like: Breadcrumbs that show where a particular page sits in a content hierarchy by displaying its parent pages Side navigation that shows the content hierarchy for the entire site, or a large portion of the site Labels and metadata that contain information relevant to the document, typically machine readable for help with search indexing Prerequisites, next steps, and additional information sections that are succinct and informative, directing users where to go next, or what they should have read before arriving at a page Escape hatches, often in the form of callouts, that offer recommendations for alternative pages if a reader ends up on the wrong page ([Location 2794](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2794)) - Next, evaluate each page in the list, using what you know about your users to determine how well each page is working. Ask yourself the following questions: Is this page useful? Is this page up to date? Is this page in the right place? As you evaluate each page, label it with what work needs to be done. Example labels include: Keep Remove Review for accuracy Merge with another document Split into multiple documents ([Location 2814](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2814)) - ask yourself, is there missing information that your users have been requesting? This missing content is called a content gap ([Location 2818](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2818)) - Ultimately, users expect your content to be: Consistent: Your content is organized with familiar structure and patterns. Users always know where they are. Relevant: The most important content that addresses the most common user needs is the easiest to find. Findable: Your content is easily accessed from any homepage or landing pages, and through search. ([Location 2826](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2826)) - you move the pages around, use this validation checklist as an auditing mechanism: Landing pages: created sparingly and guiding users to the most important documents Content types: consistently implemented and suitable for your users Page data: descriptive and consistent titles, headers, prerequisites, and next steps Navigation cues: breadcrumbs, side navigation, and escape hatches to help orient users Labels and metadata: display relevant data for users and search index Redirects: users are redirected from previous locations to new URLs after you move pages ([Location 2851](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2851)) - When you add new pages to your documentation, consider the following questions: Is it clear where this new content belongs? What adjustments to the existing information architecture are required? Does this content impact the home page and landing pages? ([Location 2860](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2860)) - Start your plan by considering how your users are impacted and answering the following questions: How are users impacted by this change? How does this change affect existing product functionality? What existing documentation does this change affect? What new documentation do we need to create to support our users? ([Location 2926](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2926)) - Tags: favorite - Once you’ve budgeted time in your planning process for updating documentation, you should also integrate documentation into your release process. Updated documentation and code should be released at the same time, guaranteeing that they both stay in sync. ([Location 2936](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2936)) - A tracking spreadsheet lists all proposed enhancements for the upcoming release.   2. Each proposed enhancement is documented in a Github Issue, and is required to have a design doc, feature owner, unit tests, and an assessment of whether or not documentation is necessary.   3. If the enhancement needs documentation, the feature owner must open a Pull Request for documentation and receive approval before the enhancement is approved for release.   4. Once the code, unit tests, and documentation are all approved for the enhancement, the enhancement is approved for launch.   5. On the release date, all approved enhancements are pushed with the new release. ([Location 2944](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2944)) - Link checkers work in one of two ways: By running against your documentation prior to publication as part of your CI/CD toolchain By running against the documentation after it’s published by crawling your document like a web page ([Location 2998](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=2998)) - Documentation linters, or prose linters, operate on the same principle as code linters. They can find, flag, and propose fixes to common issues found in documentation. Prose linters are similar to the spelling and grammar checker included with most word processors, such as when your spellchecker catches misspellings of common words. ([Location 3002](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=3002)) - Documentation linters , or prose linters, operate on the same principle as code linters. They can find, flag, and propose fixes to common issues found in documentation. Prose linters are similar to the spelling and grammar checker included with most word processors, such as when your spellchecker catches misspellings of common words. ([Location 3013](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=3013)) - As a rule, documentation should be deleted when it’s no longer useful to your users. There are a few common reasons this might happen. One is when all the users of a deprecated feature have successfully migrated away from it, the feature is being removed, and the documentation is no longer needed. Another reason to delete is when a piece of documentation is outdated or irrelevant and it’s not worth the time to fix it. ([Location 3039](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=3039)) - Plan code and documentation together with maintainability in mind. Align documentation releases with feature releases. Assign owners to documents. Automate toil with content freshness checks, link checkers, documentation linters, and reference doc generators—but be careful before automating. ([Location 3057](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=3057)) - Technical Writing Courses from Google Google’s technical writing team offers two self-guided courses in beginner and intermediate technical writing, focused on developers. Available at: developers.google.com/tech-writing ([Location 3116](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=3116)) - README checklist There are many README checklists available, but Daniel Beck’s is one of the best. It’s a useful accompaniment to Daniel’s talk “Write the readable README” which is available on YouTube. Available at: www.github.com/ddbeck/readme-checklist ([Location 3128](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=3128)) - Write the Docs Write the Docs is a global community of people who care about documentation, including programmers, tech writers, developer advocates, customer support, marketers, and anyone else who wants people to have great experiences with software. Write the Docs maintains an active online and in-person community through its Slack network, conferences, and local meetups. Available at: www.writethedocs.org ([Location 3184](https://readwise.io/to_kindle?action=open&asin=B09HLZGWKT&location=3184)) ## Related - [[3. Resources/Readwise/Books/Developer Marketing and Relations|Developer Marketing and Relations]] - [[3. Resources/Readwise/Books/Developer Relations|Developer Relations]] - [[3. Resources/Readwise/Books/Developer, Advocate!|Developer, Advocate!]] - [[3. Resources/Readwise/Books/The Business Value of Developer Relations|The Business Value of Developer Relations]] - [[3. Resources/Readwise/Books/The Developer Advocacy Handbook|The Developer Advocacy Handbook]]