Crafting Docs for Success  🔗 **Source:** [Crafting Docs for Success]() ## Highlights - Your developer documentation is naturally linked to the product it documents, but considering the crucial role it plays in the adoption, use, and marketing of your product, it should be considered a product in its own right. ([Location 315](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=315)) - Tags: aqua - Your developer documentation can become your most important asset in developer relations that fulfills a wide range of different functions: It should provide all the necessary information for developers to start working with your product as the key ingredient in your onboarding. It should be a reliable source for self-help and education. It should be a platform to keep your users informed on changes and plans through release notes, status reports, and various content updates. It can build trust and show your users how committed you are, how much you value their feedback as you shape the documentation to best fit their needs. It can help you maintain relationships with your users, build a community, and encourage collaboration. Documentation can work as an interactive tool between you and the developers using your product by making it possible for them to immediately share their thoughts and suggestions on the docs so that you can act on them quickly. It’s also a marketing tool: many potential clients will find you through your developer portal. Decision-makers also check out your documentation to see the quality of support you provide. It can be a valuable resource for your support team who can in turn provide feedback about the documentation from direct communication with users. It can become the foundation for your developer education program, webinars, courses, certification programs, and so on. ([Location 317](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=317)) - Tags: aqua - Design Thinking is a human-centered iterative design process that consists of predefined steps you can follow to understand your users, reevaluate your assumptions, define or redefine problems, and create solution prototypes that you can test. ([Location 335](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=335)) - Tags: aqua - Phase 1: Empathize Develop a deep understanding of the challenge by setting aside your assumptions and gaining insights about your users through user research. Try to get rid of any preconceived ideas you have about the tasks your users want to accomplish, how they approach them, and what obstacles they may face. Listen and explore with an open mind, and be aware of your biases so that you don’t focus on results that confirm them. Phase 2: Define Analyze the information you collected in the Empathize phase and describe the problem you want to solve. You can create personas – semi-fictional, archetypical users whose goals and characteristics represent the needs of larger user groups or target audience segments. Personas are one way to help you keep the process human-centered through all phases. Phase 3: Ideate Based on the knowledge from the previous phases, try to consider the problem from different points of view, brainstorm ideas, and identify innovative solutions. Phase 4: Prototype Experiment, and identify the best possible solution for each problem. Come up with cost-efficient ways to design scaled-down versions of your solutions that you can quickly develop, produce, adjust, or discard. Phase 5: Test Start a testing process that consists of short cycles to redefine or improve your solutions. You might gain more insights about your users or further problems might emerge, so you might need to return to previous phases and iterate. ([Location 349](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=349)) - Tags: aqua - Docs as Code is a great match for developer documentation projects because your main contributors, developers on your team and in your community, are already familiar with these workflows and tools. ([Location 440](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=440)) - Tags: aqua - it enables a culture where all contributors feel ownership of documentation. With the right support, it provides the technical foundations for an inclusive environment where everyone can contribute according to their specific skills and expertise to make your developer documentation as good as it can be. ([Location 470](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=470)) - Tags: aqua - Constant collaboration also builds trust: if your process is completely transparent, your community can continuously follow what you’re working on and how your docs evolve, and community members can be sure that their opinions are heard and acted upon. ([Location 482](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=482)) - Tags: aqua - The goal of a documentation site is to provide easily accessible, well-structured information for self-support and learning that is written, edited, and structured in a way that best fits the user’s needs. When building documentation, content is your top priority. ([Location 500](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=500)) - Tags: aqua - DITA is an open standard that defines a set of document types for authoring and organizing topic-oriented information. The latest version of DITA (1.3) includes five topic types: task, concept, reference, glossary entry, and troubleshooting. ([Location 523](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=523)) - Tags: aqua - Task: Task topics are building blocks to provide procedural information. They describe how to accomplish a task through a series of steps and can also include context, links to prerequisites and next steps, and examples. ([Location 528](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=528)) - Tags: aqua - Concept: Concept topics provide background information and other essential information that the user needs to know to understand a system, product, or solution. They can explain features and components, introduce technology, or outline a process. ([Location 529](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=529)) - Tags: aqua - Reference: Reference topics provide data to support performing a task and usually include information that is looked up rather than memorized. They are often displayed as lists or tables. ([Location 531](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=531)) - Tags: aqua - make sure that the documentation you are planning is: Desirable: Conduct various forms of user research to ensure that your solution fulfills user needs. Viable: Interview stakeholders to ensure that your solution corresponds to business needs. Feasible: Ensure that you have the resources, developer capacity, time, and technical background to build your solution. ([Location 599](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=599)) - Tags: aqua - Attitudinal or behavioral: The purpose of attitudinal research is to understand users’ beliefs (what they say), while behavioral research seeks to understand users’ actions (what they do). ([Location 618](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=618)) - Tags: aqua - Qualitative or quantitative: Qualitative research answers how and when a certain phenomenon occurs by providing non-numerical information. Quantitative research is an investigation using statistical, mathematical, or computational techniques. ([Location 620](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=620)) - Tags: aqua - Before starting user research, always agree with your team on Goals: What’s the purpose of this research, what are you trying to achieve, what insights will this research generate, and how will you use those insights? Problems: What is the problem you are trying to solve? Assumptions: What assumption or belief do you want to test and what do you need to validate or explore? Information: What do you need to know to be able to make a decision? Has anything been done related to this research already (e.g., other research or analysis)? ([Location 622](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=622)) - Tags: aqua - Competitive analysis: Compare strengths, weaknesses, features, flows, and the user experience of your competitors relative to your documentation plans based on user feedback. ([Location 637](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=637)) - Tags: aqua - Interviews: Meet your users and people from sales, marketing, and company leadership to discuss in depth how the participant experiences the topic in question. ([Location 639](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=639)) - Tags: aqua - Usability testing: Usability testing involves asking potential or current users of a product or service to complete a set of tasks and then observing their behavior to determine the usability of the product or service. ([Location 640](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=640)) - Tags: aqua - Moderated (remote) usability testing allows you to conduct user research with participants in their natural work environment. Participants are observed and interacted with while they complete the tasks for the test. Moderated testing is best for complex tasks that do not have a structured sequence of steps or where more interaction and questioning will benefit testing. ([Location 642](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=642)) - Tags: aqua - Unmoderated (remote) usability studies are designed to measure how satisfied a user is with the interface of your documentation. The idea is that participants will work through a task in their usual environment without a moderator present. They are shorter and less complex than moderated usability studies. ([Location 645](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=645)) - Tags: aqua - Card sorting: A quantitative or qualitative method that asks users to organize items into groups and assign categories to each group. This method helps create or refine the information architecture of your documentation by exposing users’ mental models. ([Location 647](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=647)) - Tags: aqua - Tree tests: Tree tests are helpful in validating the information architecture. In a tree test, users are given a task and shown the top level of a site map. They are then asked to talk about where they would go to accomplish the task. ([Location 650](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=650)) - Tags: aqua - Surveys, questionnaires: Questionnaires and surveys are an easy way to gather a large amount of information about a group. This quantitative data can help you to have a better understanding of specific topics that you can research further with other methods. ([Location 652](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=652)) - Tags: aqua - Analytics review: Site analytics provide quantitative data about usage and identify possible flow breaks that you can test further in usability research. ([Location 654](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=654)) - Tags: aqua - Systematic developers follow a defensive, top-down approach and take precautions. They learn about concepts and architecture and gain a deep understanding of the technology before they start to use it. They read the documentation thoroughly and usually follow proposed processes and recommendations. They set up their development environment as instructed and use and modify example code. Systematic developers feel accomplished when they write clean and elegant code to complete a task. ([Location 712](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=712)) - Tags: aqua - Opportunistic developers follow a bottom-up approach. They start coding immediately focusing on solving the problem at hand and only gather as much information as they need to work on the task. They scan the documentation to find the information they need and are less likely to follow proposed processes. They might deviate from the recommended workflow or order of steps and usually search the Web in parallel with using the official documentation and coding. Opportunistic developers are explorers who take pride in solving problems. ([Location 716](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=716)) - Tags: aqua - Pragmatic developers combine systematic and opportunistic approaches. They learn until they develop a sufficient understanding of the technology, but they don’t delve deeper than needed for accomplishing the task. ([Location 720](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=720)) - Tags: aqua - They use the documentation and other resources to learn enough to start the task beforehand and then consult these resources again when they encounter an obstacle. Pragmatic developers take delight in building robust applications. Although each developer might have a characteristic approach, they might follow different approaches for different tasks, or under different circumstances. Regardless of the approach, as a bare minimum, they all need Conceptual information (concept topics) Procedural information (task topics) References (reference topics) Code examples Clear navigation Efficient search ([Location 721](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=721)) - Tags: aqua - Your documentation should also serve your own support team, and it should work both ways. ([Location 736](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=736)) - Tags: aqua - Product owners, business analysts, and project managers will visit your docs to evaluate if your solution would be a good fit for their projects. When they do so, they are not only interested in the technology you developed but also in the support you provide, the frequency of your updates, your product road map, new features and other plans for the future, how you communicate with your users, and how they can become part of your community. ([Location 739](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=739)) - Tags: aqua - DevRel practitioners, developer advocates, and technical community managers will come to your documentation for learning materials that they can use in their own communities. They will be on the lookout for best practices they can use and ways to connect with your community. ([Location 743](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=743)) - Tags: aqua - Documentarians working at companies that use your technology will consult your documentation as they are developing their own content. ([Location 745](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=745)) - Tags: aqua - Proto-personas are based on the assumptions of stakeholders; they represent what you think your users are like. They are typically utilized in the startup product world, especially during the phase of searching for market fit. ([Location 777](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=777)) - Tags: aqua - Personas are based on actual research data. You will have to revisit and revalidate both types of personas multiple times during later phases of the process and any time there is a shift in the target audience segments, but proto-personas need a validation early on for you to be able to work with them. ([Location 778](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=778)) - Tags: aqua - For personas of a developer documentation site, we found that describing the following aspects proved to be helpful: A fictional name and photo that makes the persona easier to relate and refer to Role, job title, major responsibilities Keywords that quickly help us identify the main characteristics of a persona Goals that describe what the user would like to accomplish Behavior that describes what the user does as part of their job or as a learning strategy Factors you must keep in mind to fulfill the persona’s needs (e.g., you have to provide step-by-step guidance for a junior developer to set up their environment) What you must not do (for example, don’t show complex solutions first to a user with entry-level knowledge) ([Location 793](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=793)) - Tags: aqua - A developer documentation site typically needs content like the following: Onboarding tutorials and concept topics (different personas usually need different onboarding journeys) Concept topics and tutorials for different features of the product (for different experience levels) Use cases, best practices (for experienced developers, but useful for all skill levels and other target audience segments as well) References (like API reference, error messages) Road map Try-out section, sandbox Information for contributors Information for community involvement Ways to get involved in user research Results of past user research activities Ways to provide feedback Ways to get support Legal information (copyright, license, privacy policy) ([Location 819](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=819)) - Tags: aqua - The Conventional Commits3 specification provides a lightweight set of rules for creating a commit message history you can build automation on. ([Location 1034](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1034)) - Tags: aqua - When you describe the tone of your documentation, you can get inspiration from the voice of your brand, but overall, documentation style guides usually define a clear, simple, friendly, and conversational tone. ([Location 1268](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1268)) - Tags: aqua - use present tense in general and avoid using future tense where possible. ([Location 1270](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1270)) - Tags: aqua - talk to the users in the second person, address the user as “you,” and avoid the use of gender-specific, third-person pronouns such as he, she, his, and hers and the use of we, except when we want to emphasize something that the platformOS team did. ([Location 1271](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1271)) - Tags: aqua - write in active voice. Active-voice sentences are more direct and easier to understand than passive-voice sentences, so they are a better fit for technical content. ([Location 1275](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1275)) - Tags: aqua - add rules for the capitalization of titles, headings, and terms specific to your product. ([Location 1277](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1277)) - Tags: aqua - Explain basic rules for punctuation, for example, in titles and list items, and take a stand on whether you want your contributors to use the serial comma or not and stick to the approach you chose. Clarify how you want contributors to write numbers – when to use numerals and when to spell out numbers. ([Location 1279](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1279)) - Tags: aqua - Add guidelines for using lists. Explain to use numbered lists for sequential task steps and bullet lists for sets of options, notes, and the like. ([Location 1282](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1282)) - Tags: aqua - Potential additional specifications for images could include Internationalization or localization, along with translation guidelines Guidelines on whether image annotations, such as legends pointing out different screen areas, are allowed or encouraged Rules on whether captions are mandatory Accessibility requirements, such as contrast, color choice, and alt text Information on whether your output automatically adds numbers to image and figure captions Details on whether your output enables zoom-in on images with a click ([Location 1296](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1296)) - Tags: aqua - You should continuously work on making your documentation more accessible and usable to the widest possible audience. One ingredient to achieving this goal is writing accessible and inclusive content. Collecting guidelines for accessibility in your documentation style guide brings this aspect to the attention of your contributors, reviewers, and editors. ([Location 1309](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1309)) - Tags: aqua - The concept topic always includes the following: Title: A concise description of what the topic is about. We prefer to use nouns in concept topic titles to differentiate them from tutorials right at the title level, for example, Pages. Definition: A clear definition of the concept topic that answers the question “what.” Based on the previous example for the title, the definition would explain what pages are, why they are used, and what their benefits are. Detailed information: Describes further useful information about the concept. We encourage contributors to structure their content by the different aspects they explain, for example, in the case of pages, named parameters, page configuration, available properties, etc. Can contain examples, diagrams, screenshots, and videos. Related topics: Links to related topics to map out connected information. ([Location 1331](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1331)) - Tags: aqua - All of your tutorials should follow the same format (as defined in the tutorial template): Title: Specify the format for the title to keep your documentation consistent and differentiate between different content types. Goal: What the tutorial helps the user do, what the user will accomplish by the end of the tutorial. Requirements: What background knowledge or resources the user needs to be able to successfully finish this tutorial. Steps: Brief overview of the steps in this tutorial. Step 1, Step 2, etc.: Detailed descriptions of steps, with screenshots, code examples, etc. Next steps: What the user can do next; if the tutorial is part of a series, link to the next tutorial in the series. ([Location 1362](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1362)) - Tags: aqua - For describing a REST API, it’s practical to follow a predefined standard. Currently, the most widely used standard is the vendor-neutral OpenAPI Specification14. Following a standard allows you to programmatically parse and display information. ([Location 1450](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1450)) - Tags: aqua - This checklist summarizes my recommendations for the elements of a minimum viable developer documentation style guide. Feel free to use it as an inspiration for your own documentation style guide, for planning, or for tracking your progress. Introduction: Goal of the style guide, what it includes Detailed description of the audience, personas included Writing guidelines Language and spelling Tone Present tense Second person Active voice Capitalization Punctuation Numbers Lists Format Formatting guidelines Headings Code examples Tables Paths Images Videos Accessibility Inclusive language Templates for topic types Task Concept Reference ([Location 1462](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1462)) - Tags: aqua - The Atomic Design methodology consists of five stages, which are as follows: 1. Atoms are the smallest building blocks of UI elements, such as buttons, icons, labels, and inputs.   2. Molecules are combinations of atoms that create more complex UI elements, such as forms, search bars, and navigation menus.   3. Organisms are combinations of molecules that create even more complex UI elements, such as headers, footers, and product listings.   4. Templates are the final layouts that bring together all the organisms, molecules, and atoms to create specific pages or views within an application or website.   5. Pages are the final product, where the templates are filled with real content to create a complete user interface. ([Location 1666](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1666)) - Tags: aqua - Avoid any unnecessary changes that could lead to increased complexity, confusion, and inconsistency in the user interface Focus on the needs and expectations of your users so you can come up with solutions that address real user pain points and improve the user experience Measure the impact of the change on the user experience and validate the effectiveness of the change and make further improvements if necessary Save time and resources by prioritizing your efforts and making the most of your design team’s resources ([Location 1685](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1685)) - Tags: aqua - Automatic documentation generation: Automatically generate documentation for your API from its source code or from an OpenAPI specification file. ([Location 1795](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1795)) - Tags: aqua - Code examples: Include code examples in various programming languages to help developers understand how to use the API. ([Location 1796](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1796)) - Tags: aqua - Interactive documentation: Many API documentation generators offer interactive documentation that allows developers to try out the API’s endpoints and see the responses in real time. ([Location 1797](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1797)) - Tags: aqua - Test requests: Some API documentation generators allow developers to send test requests directly from the documentation to see how the API responds. ([Location 1799](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1799)) - Tags: aqua - Search: Allow developers to quickly find the documentation they need. ([Location 1800](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1800)) - Tags: aqua - Customization: Customize the look and feel of the documentation, including colors, fonts, and logos. ([Location 1801](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1801)) - Tags: aqua - Versioning: Support versioning, making it easy to maintain and document changes to the API over time. ([Location 1802](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1802)) - Tags: aqua - SwaggerHub: A cloud-based platform for designing, building, and documenting APIs using the OpenAPI specification. It provides a collaborative environment for teams to work on API projects, with features such as version control, team management, integration with popular development tools, and automatic documentation generation. ([Location 1805](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1805)) - Tags: aqua - Redocly15: An open source tool for generating API documentation from OpenAPI specifications. It provides a customizable interface for viewing and interacting with API documentation and supports a variety of OpenAPI features, including endpoint descriptions, parameters, response codes, and security definitions. It also includes features for customizing the documentation layout and appearance, such as changing the color scheme and adding custom CSS. ([Location 1808](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1808)) - Tags: aqua - Stoplight16: A platform for designing, documenting, and testing APIs that includes a tool for generating API documentation. The REST API and OpenAPI documentation generator provided by Stoplight offers various options for your API consumers to experiment with your APIs, like test requests or code examples in many different programming languages. ([Location 1812](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1812)) - Tags: aqua - Continuous integration (CI) means that code is continuously tested, integrated with other code changes, and merged. Continuous deployment or continuous delivery (CD) means that code is continuously deployed with each patch to the entire code base. For documentation, CI/CD means that when you edit content and merge it to the Git repository of your production site, it triggers the publication process: it builds your site, runs tests, and deploys it to the live environment. ([Location 1831](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1831)) - Tags: aqua - Developers provide information and code examples for technical writers in the form of drafts, descriptions, or videos. Account managers and other team members interacting with clients share details about where more support would be needed and write drafts themselves. Developers and designers in our team work on making our developer portal a high-performance site with great usability facilitating the results of our UX research and feedback. Community contributors provide feedback, patches, and new content to our documentation. External contributors review and edit our documentation to suggest changes or improve clarity. ([Location 1941](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1941)) - Tags: aqua - Constant collaboration builds trust. ([Location 1953](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1953)) - Tags: aqua - Some ways community members can contribute: Participating in various types of user research at all phases of your documentation development process Testing your documentation and reporting errors Providing feedback on documentation topics, pointing out processes that are difficult to follow, asking for missing information Providing feedback on your editorial workflow, where they get stuck, what they would need to make it easier Participating in discussions about your future plans, helping you prioritize Participating in discussions with other community members, helping newcomers Editing documentation topics, fixing typos, adding missing information, removing outdated information Writing documentation topics, providing use cases Reviewing documentation topics others have written Providing feedback on your communication, what they need more information on, what channels work for them ([Location 1956](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=1956)) - Tags: aqua - Make it easy to get involved for all segments of your target audience, offer different ways to contribute both regarding the time contributors have to put in and the skill level they need. ([Location 2038](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2038)) - Tags: aqua - Develop an editorial workflow that works for internal and external contributors, and ensure that contributors get quick and precise feedback. ([Location 2044](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2044)) - Tags: aqua - Information on how to give feedback A step-by-step tutorial on how to update existing content and submit new content A link to the Style Guide and a description of what the contributor will find there A link to the templates and a short description of what they are used for A way to get in touch with the documentation team Based on feedback from your contributors, you can adjust and improve your Contributor Guide just like any other part of your documentation. ([Location 2050](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2050)) - Tags: aqua - Release notes share what you’ve done; road maps show what you are planning to do. ([Location 2060](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2060)) - Tags: aqua - sharing status reports is a great way to keep our community updated on what we’ve achieved, what we are working on, and what we are planning for the near future. ([Location 2064](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2064)) - Tags: aqua - The community guidelines typically include the following: The expected behavior of community members, like being friendly, patient, respectful, and considerate. The tone, language, and conduct for all communication within the community, be it virtual or in person (you might want to list the channels where these rules apply). This part usually includes rules against bullying, hate speech, and harassment. Content guidelines that specify what kind of content is allowed and not allowed on community channels, for example, providing rules for self or company promotions, but also for explicit content or spam. What to do if you’ve encountered a violation of the rules in the community. Moderation policies that describe how moderators enforce the rules and the consequences for community members who violate them. ([Location 2093](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2093)) - Tags: aqua - Accessibility ensures that people with disabilities or impairments (including visual, auditory, cognitive, and motor impairments) can use digital products and services efficiently. ([Location 2121](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2121)) - Tags: aqua - Inclusiveness ensures that individuals from diverse backgrounds and various circumstances have the opportunity to actively participate and derive benefits from the products, services, and information provided. ([Location 2122](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2122)) - Tags: aqua - According to the World Health Organization, nearly all individuals will experience disability at some point in their lives, either temporarily or permanently. ([Location 2130](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2130)) - Tags: aqua - The four main principles of the WCAG standards state that web content should be Perceivable: Presented in a way that users can perceive it using their senses. This includes providing alternative text for images, captions for videos, and clear content structure. Operable: Users should be able to navigate and interact with web content using a wide range of input methods. This includes making the content keyboard accessible, allowing users to skip repetitive content, and providing understandable and predictable navigation. Understandable: Presented in a clear and understandable manner. This involves using plain language, organizing content logically, and providing instructions and error messages that are easy to comprehend. Robust: Web content should be developed using technologies that are compatible with a variety of user agents, including assistive technologies. This ensures that the content remains accessible even as technology evolves. ([Location 2153](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2153)) - Tags: aqua - Based on the requirements of an accessible content structure, there are some basic guidelines to follow when writing content for your documentation. Use headers for structuring your content: The Markdown format you write in is translated into semantic HTML to help screen readers navigate through the content. Use headers as described in the style guide and follow the provided templates to ensure consistency. Never skip a header level for styling reasons. Improve readability by using concise language, writing short paragraphs, and using lists where applicable. Use alternative text for images and icons. Keep in mind that screen readers read this text out loud. If the image serves a function as part of the documentation, describe the image in detail. Users should receive the same information from the alt text that they would receive if they saw the image. Include the data for charts or graphs in the alt text. When you use screenshots to show what the user has to do, the alt text shouldn’t repeat the information already described in text. Decorative images don’t need alt text – it would only be a distraction. When a screen reader encounters an image with null alt text, it skips over the image without acknowledging its existence. On the other hand, if an image lacks an alt attribute, the screen reader will announce the file name of the image. This could potentially be a significant disruption for individuals who rely on screen-reading technology. If you insert an image, pay attention to the contrast ratio, image quality, and its size in kilobytes. The smaller the image, the more accessible it is because images with smaller file sizes load faster, reducing wait times for users, particularly those with slower Internet connections. Use informative link text: To help keyboard navigation, add the information into the link text. For example, instead of writing “learn more” or “click here”, write the topic title. If you’re using videos, make sure to also provide the information in text. Not everyone finds videos easy to use. Also, many people like to speed up videos to save time, or read the closed captions if they find it easier to learn by reading than by listening. ([Location 2221](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2221)) - Tags: aqua - What Would a Sustainable Internet Look Like? The Sustainable Web Manifesto4 describes the requirements for a sustainable Internet. Clean: The services you provide and services you use should be powered by renewable energy. Efficient: The products and services you provide should use the least amount of energy and material resources possible. Open: The products and services you provide should be accessible, allow for the open exchange of information, and allow users to control their data. Honest: The products and services you provide should not mislead or exploit users in their design or content. Regenerative: The products and services you provide should support an economy that nourishes the people and the planet. Resilient: The products and services you provide will function in the times and places where people need them most. ([Location 2407](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2407)) - Tags: aqua - Technical writers are responsible for creating and maintaining the content of your developer documentation. They collaborate with SMEs (subject matter experts) to research, organize, and write content and ensure the accuracy and consistency of the documentation. They may also be involved in designing the structure and layout of the documentation, choosing the appropriate tools and technologies for the project, and managing and fine-tuning the editorial workflow. Most often, technical writers review and edit documentation topics submitted by internal or external contributors. If you have technical editors on your team, you can divide writing and review tasks between writers and editors. ([Location 2632](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2632)) - Tags: aqua - The UX researcher’s role focuses on the development and execution of research studies and usability tests that inform the design and development of user experiences for your developer documentation. ([Location 2641](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2641)) - Tags: aqua - The information architect (IA) is involved in developing and optimizing the information architecture of your documentation, ensuring that users can easily find the information they need. ([Location 2654](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2654)) - Tags: aqua - The interaction designer role involves designing and optimizing the way users interact with your developer documentation. This includes defining and improving interaction design processes and staying up to date with industry trends and best practices. For interactive developer documentation, it is beneficial to have someone who understands common features like “Try it out” from the Swagger UI output commonly seen in REST API websites. ([Location 2660](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2660)) - Tags: aqua - UX writers create the text that appears on buttons, forms, menus, and other interface elements. They also write microcopy, such as error messages, tooltips, and notifications. ([Location 2666](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2666)) - Tags: aqua - Working closely with the UX researcher and the information architect, UX designers develop user flows, wireframes, and prototypes to create an intuitive and seamless user experience. ([Location 2668](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2668)) - Tags: aqua - Based on the wireframes and prototypes, the UI designer creates visually appealing interfaces for your documentation that include layouts, fonts, icons, buttons, and other graphical elements. ([Location 2672](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2672)) - Tags: aqua - Developers working on your documentation can contribute in two distinct ways: by developing, adjusting, and improving the documentation site and by providing information to technical writers as subject matter experts. ([Location 2679](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2679)) - Tags: aqua - The QA team is responsible for reviewing, testing, and validating the documentation to identify any issues or inconsistencies before it is published. They set up automated tests; do manual testing on the site; check the accuracy and correctness of code examples; report identified issues, inconsistencies, or errors using your issue management tool; and verify that the reported issues have been resolved. ([Location 2690](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2690)) - Tags: aqua - DocOps, short for Documentation Operations, is the practice of integrating documentation processes and workflows within the broader context of software development and operations. ([Location 2696](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2696)) - Tags: aqua - Depending on the size of the business and the resources dedicated to the documentation, the project can have its own product manager, project manager, or scrum master (if you follow the scrum methodology), while in other teams, the responsibilities of these roles are divided between the documentation lead and other members of the team. ([Location 2700](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2700)) - Tags: aqua - Some notable communities and conferences for professionals working on developer documentation: Write the Docs1: Write the Docs has an active online community where you can engage in discussions, share resources, and seek advice on documentation-related topics. Write the Docs is also the name of a series of conferences held in different locations worldwide, including online, that focuses on all aspects of documentation and technical writing. API The Docs2: API The Docs events serve technologists involved in the documentation, developer relations, marketing, and UX of API programs: members of API teams who want to create great developer experiences and, ultimately, developer success. DevRelCon3: DevRelCon is a series of conferences aimed at sharing and levelling up knowledge of developer relations including topics related to developer experience, community, and developer marketing. ISTC4 and TCUK5: The Institute of Scientific and Technical Communicators (ISTC) is the largest UK body representing information development professionals. TCUK, or Technical Communication UK, is the ISTC’s annual conference for everyone involved in writing, editing, illustrating, delivering, and publishing technical information. STC6 and STC Summit7: The Society for Technical Communication is the world’s largest and oldest professional association dedicated to the advancement of the field of technical communication. The STC Summit is an annual conference that gathers technical communicators from various industries. It covers a wide range of topics related to documentation, content creation, and user experience. ([Location 2716](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2716)) - Tags: aqua - Docs Like Code8 book and docslikecode.com9 by Anne Gentle Docs for Developers: An Engineer’s Field Guide to Technical Writing10 by Jared Bhatti, Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse The Product is Docs: Writing technical documentation in a product development group11 by Christopher Gales12 and the Splunk Documentation Team13 Documenting APIs: A guide for technical writers and engineers14 course and idratherbewriting.com15 by Tom Johnson Docsbydesign.com16 by Robert Watson Courses about API technical writing by Peter Gruenbaum on Udemy17 ([Location 2737](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2737)) - Tags: aqua - Readability refers to the ease with which a reader can understand and navigate the information presented, and as such, it directly impacts the effectiveness and usability of developer documentation. ([Location 2860](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2860)) - Tags: aqua - Clarity in the writing helps avoid misunderstandings, while a clear information architecture aids users in finding the information they are looking for. ([Location 2865](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2865)) - Tags: aqua - Findability of information is key to developer documentation, so make sure that your site is indexed in general search engines and test that searches for important keywords return relevant results. ([Location 2866](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2866)) - Tags: aqua - Developer documentation plays an important role in developer onboarding, education, communication, community engagement, marketing, and support. It ([Location 2971](https://readwise.io/to_kindle?action=open&asin=B0CD9RHQ4F&location=2971)) - Tags: aqua