Documentation

Contents

• Understand your audience
• Planning your documentation
• Drafting documentation

Understand your audience

Identifying the goals you have for your users

Once you determine your goal for users of your product, write it down. Later, you can measure the success of your documentation by how well it meets your goal.

Understanding your users’ needs and how documentation addresses them

Not every user is the same, and you can’t meet every user’s needs. Prioritize the users who are most important for your product or business.

Condensing your findings into personas, stories, and maps

 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.

User personas

Condensing your findings into personas, stories, and maps

If you have more time, you may find it useful to write user stories alongside your personas. User stories are short written summaries of what a user is trying to achieve and are a nifty way to condense your users’ needs to keep them front of mind for the planning, writing, editing, publishing, and maintenance that comes next. You may be familiar with the idea of user stories from working in Agile product teams.

A user story tends to follow the same format: As a [type of user], I want [activity] so that I can [goal].

User stories

Condensing your findings into personas, stories, and maps

 A user journey map is a diagram showing the path a user takes through a product or website while trying to accomplish a particular task.

The map usually covers all routes or “channels” a user may take when interacting with your software and documentation.

The map is a timeline, tracking what a user does at each point in their journey and what they feel or experience at each step.  

User journey maps

To create a user journey map:

1. Define the task the user is trying to accomplish.
2. List the channels a user may interact with (e.g., your website, docs, your code repository, or the app itself).
3. Piece together the steps a user takes through each channel (e.g., discover, sign up, install, configure, test, run, review).
4. List the user experience at each step (e.g., what they are doing, feeling, thinking).
5. Connect the channels, steps, and experiences in a flow.

Testing your assumptions with a friction log

Friction can manifest in different ways. Frustration, anger, disappointment, and stress are all symptoms of friction that result in the same thing: distrust and disengagement with your software.

    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 behaviour you expect and the actual behaviour of your software. The bigger the gap between expectation and reality, the bigger the opportunity to improve your docs or software.

    The best friction logs have a tight scope to prevent sprawl and keep results actionable. Pick a user and a scenario with a clear beginning and end, for example, a developer installing your software for the first time. Note the scenario and any other test information at the top of the page, such as the environment or version you’re using.

Testing your assumptions with a friction log

Goal: Start using Corg.ly API

1. Sign up for a paid Corg.ly account.
2. Opened Corg.ly website.
3. Navigated to a web form for sign-up. Had to scroll to the bottom of the page. Difficult to find. Maybe add to top of page?
4.  Completed form. Put in credit card information.
5.  Clicked submit button. Did not receive confirmation it had been submitted. No error generated.
6. Noticed some form fields were blank. Did the empty fields stop the form from submitting?
7. Filled in blank fields.
8. Clicked submit button. Received confirmation message and reassuring information has been sent.

You may find it useful to color code your friction log to indicate positive and negative user experiences. For example, green could indicate steps that were easy to complete, offered clear evidence of success, and guided you to the next step, or red for steps that were particularly frustrating or stopped you from progressing.

Creating an initial sketch of your users

To write effectively for users, you need to understand who they are and what they want to achieve. Start by gathering and reviewing any existing materials you already have about your product or your users. These could include old emails, design documents, chat conversations, code comments, and commit messages. Reviewing these artifacts will help you build a clearer picture of how your software works and what you intend your users to do with it.

    Users also have their own goals that may or may not match those of your organization. An initial review can help identify any initial gaps or mismatches between these different sets of goals.

1. Support tickets: Support tickets are an existing data source and a gold mine for understanding your users. Nothing beats the content of a support request sent in the heat of the moment by a frustrated user for understanding what your users need most. 
2. Direct interviews
3. Developers surveys

Sources

Creating an initial sketch of your users

1. Outline your users’ needs
2. What is this product?
3. Will this product solve my problem?
4. What features are available?
5. How much does it cost?
6. How do I get started?
7. Other questions are going to be very specific to your product, your users, and their goal:
8. How do I authenticate against your API?
9. How do I use a specific feature?
10. How do I troubleshoot a specific problem?

Questions:

Planning your documentation

Content types

 The most basic content type for developers is code comments. code comments document design decisions and tradeoffs made when writing code.

        The tenets for good code comments are to:

•         Keep them brief
•         Make them relevant
•         Use them liberally, but not excessively

​​​As a code base evolves, it’s useful to preserve the context for past decisions, and a single inline code comment before a particularly complex piece of code can save future developers a lot of time.

Code comments

Note:
        Even as a solitary developer working on a project, code comments can be a tremendous help. If you’ve put code aside and returned to it after weeks or months, you may have experienced bewilderment at what you were doing or why you made certain choices. Comments help you reorient to your own code.

Content types

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. You can also write READMEs for important subfolders that require additional summaries or explanations. A README contains basic information like What the code does at a high level

READMEs

•  How to install it
• Troubleshooting steps
• Who maintains the code
• License information
• A changelog
• Basic examples
• Links to more in-depth resources and documentation

Content types

READMEs

A README needs to be concise, informative, accurate, and up to date. As you continue working on code,

Content types

Getting started documentation

Getting started content also acts as a starting point for more advanced pieces of content. Common mistake organizations make is to only produce advanced documentation, like how-to guides. But you really want to make sure that all types of users are supported, whether they’re advanced or just evaluating your service.

• 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?

Content types

Conceptual documentation

 Conceptual documentation helps users understand the concepts and ideas behind your service. It describes how your service works for your users.

        Meeting notes, design documents, whiteboard diagrams, and internal documentation is the great source material for your service’s conceptual content.

Content types

Conceptual documentation

List any related documentation, including tutorials and how-to guides that implement the concept.

Limit the number of concepts explained in a single document. Readers are generally good at absorbing one core concept at a time. If you’re explaining several new concepts, things get complex very quickly and users may struggle.

By keeping conceptual documentation simple for your readers, beginners will feel comfortable learning about your service, and advanced users will appreciate the efficiency it affords them.

Content types

Procedural documentation

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.

People read documentation to solve a problem or accomplish a task, and they want to do so as quickly and effectively as possible.

Make the guide stand on its own as much as possible with all the actions users need on a single page.

Keep the number of steps limited to what’s necessary for your users. When a procedure contains many steps, the procedure looks overwhelming and complex to users. Longer procedures also create more opportunities for mistakes and tend to require more maintenance.

Avoid lengthy explanations. A few sentences of explanation or a well-placed image is useful, but too much additional content within a procedure tends to overwhelm users. A good practice is to write procedures that allow a user to see two or more steps on a standard monitor screen. If you find your procedure contains many explanations, consider separating that information out into a conceptual guide. Note that this doesn’t apply to code examples.

Content types

Tutorials

Teaches users how to achieve a specific goal. Tutorials help users test an integration without implementing real code. Good tutorials provide users with an environment they can use for learning and may even offer test data or tools to use.

        If your tutorial includes more than ten steps, you’re trying to solve a use case that’s too complex, or you’re combining too many actions in one document. Long, time-consuming tutorials make it less likely that a user will successfully finish.

        If you can’t condense a long tutorial—or any procedural content, for that matter—into fewer steps despite your best efforts, it could mean the service itself is too complex. There may be steps that should be combined, automated, or omitted from the service—and that’s a conversation you should have with the product developers.

Content types

Tutorials

Note:

Complex documentation helps you identify potential user challenges and can be an opportunity to improve the service itself. Discuss with your development team whether spending multiple hours on a single document is the user experience your organization wants. If, on the other hand, you’re the one who introduced the complexity into the system, that should be a much easier conversation.

Content types

How-to guides

How-to guides are the core type of procedural content. A how-to guide shows how users can solve actual business problems by performing specific steps with your service.

How-to guides are a true differentiator for your users: a single document that helps them build a solution to their problem. While tutorials focus on learning, a how-to guide is based on action with users implementing real code.

When planning how-to guides, pay attention to your users’ needs and interpret your company’s strategy of what you want your users to do. Plan carefully and be selective, as how-to guides are labor-intensive to write and maintain. You could lead users astray by documenting edge cases at the outer boundaries of your service’s capability .

Content types

How-to guides

A good pattern for writing how-to guides is to keep words simple, make actions clear, and continuously reinforce the problem the guide solves.

Include prerequisites at the start of your guides. Prerequisites include any dependencies, such as installing a required version of your system or packages.

Content types

How-to guides

Effective how-to guides keep users on a single page as much as possible. It’s tempting to use a link every time another page exists for a term or concept that you mention, but clicking too many links adds more distractions for users. As opposed to Wikipedia, which uses links liberally to teach you new things you didn’t know existed, you can help your users focus by creating a how-to guide on a single page.

Content types

Reference documentation

API documentation is a trusted reference for your users to start building. Good API documentation:

• Provides a detailed reference for all its resources and endpoints
• Offers plenty of examples
• Lists and defines status codes and error messages

An API reference should be concise and minimalistic. It’s a good practice to introduce your API by sharing important information like the standards it follows and how responses are formatted (for example, REST and JSON)

The best way to provide a comprehensive reference of your API is to annotate your code with descriptive comments and autogenerate a reference from the source.

Content types

Glossary

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.

Note:
Limit external links in glossaries. It’s tempting to link to external sites, especially if you’re using third-party terms. However, external links put your content at the mercy of third parties, trusting that they’ll keep the resource up to date and in the same location.

Content types

Troubleshooting documentation

 Users often find gaps and limitations in your service faster than you can fix them. As you or your users identify known issues in your product, you can document workarounds in a variety of ways using troubleshooting documentation.

Make sure you include a solution (or fix) with the description of the problem.

Organize the issues in a way that makes the most sense to your users. You can organize issues by descending order of frequency—from most likely to least likely—or in chronological order of where users might encounter them in their workflow. The important thing is to give your user a logical flow for finding the right information.

Content types

Troubleshooting documentation

When users reach a troubleshooting page, they’re often trying to fix a problem that’s frustrating to them. Help them solve their problem as quickly as possible.

Another type of troubleshooting reference is to list all of your error messages and provide more information about causes and solutions. This allows users to copy and paste their error message into search and find more context around the issue that they’re having.

Content types

Change documentation

A changelog provides a helpful historical record for internal teams like support and engineering.

Whenever there’s a significant or breaking change, provide information for what, when, and why this occurred. Not only is it helpful in the moment when you’re letting users know that something changed, but if they’re looking backwards and trying to troubleshoot an issue, they can see when a change took place that may have affected them.

List changes in chronological order, including data like:

• Previously supported versions, integrations, or deprecated features
• Name changes of parameters or important fields
• An object or resource moved

Content types

Change documentation

Release notes are another helpful type of documentation. Release notes provide a 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.

Content types

Change documentation

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. Example entries for release notes include:

• New features
• Bug fixes
• Known bugs or limitations
• Migrations

Planning your documentation

Now that you understand the content types and patterns that best serve your users, you can create a documentation plan. A documentation plan functions as a flexible outline, making it easy to map out a user journey through the content you write.

• Who is your target audience? (You might already have a user persona for them.)
• What are the biggest takeaways you want them to have from your launch?
• In order of importance, what features are you releasing?
• What do users expect from your launch?
• Is there any knowledge users need before they start using your product or features?
• What are the use cases you’re supporting?
• Are there known issues or points of friction users could stumble upon?

Answering these questions creates a context—and with your context in place, you can decide what to build.

Drafting documentation

Setting yourself up for writing success

If you’re writing code on a regular basis, you probably spent a lot of time learning how to set up your coding environment in the way that works best for you: your preferred IDE, color themes, tools, and key bindings are things you experimented with until you found your comfort zone. Writing requires similar experiments and experience to find what’s right.

Choosing your writing tools

When choosing your writing tools, consider two important factors: the format for your final content, and the shareability of drafts.

Most documentation you write will be published online, so your final format will likely be Markdown, HTML, or wikiscript.

Any text editor can output in these formats, so there’s no need to learn a new set of tools. The same text editor you use for your code also works for your documentation.

Breaking through the blank page

You can start your document by listing the information you’ve already gathered at the top:

• Audience
• Purpose
• Pattern

Defining your document’s title and goal

You can define your document’s title based on the audience, purpose, and content pattern for the document. The title should be the shortest, clearest rephrasing of the document’s purpose from the user’s perspective.

The title of the document should summarize the goal for reading the document. Anyone who clicks on your document title will know exactly what they’re getting

The goal of each of these documents is defined in the title. Limit your document to only one goal. If your document has several goals, you probably need multiple documents.

Creating your outline

Now that you’ve defined your title with the goal for your reader, consider all the steps that your reader needs to reach that goal. Start writing down all of these steps, and don’t worry about whether or not it’s in the right order.

If the goal is to understand a particular technical concept, write down all the parts that make up that concept. If the goal is to complete a technical task, write down all of the subtasks the reader needs to complete. If you made a friction log as part of your research, this is a good time to review it.

Meeting your reader’s expectations

Consider what your reader needs to know and do to successfully complete the goal you stated in the title. Imagine their expectations and knowledge, drawing upon the research you’ve already done. The order of information in your outline should meet your user’s expectations and needs.

The knowledge your reader has is different from yours, and their experience with what you’ve built won’t be as extensive.

Review the initial outline you’ve written. Rearrange the steps if needed, focusing on how best to help your readers. You can start by grouping tasks hierarchically, splitting up some of the tasks if you think they might be too complex, and grouping similar tasks together.

Completing your outline

Review the outline for the document and consider your readers. Ask yourself the following questions:

• Is there additional introductory or setup information that readers need to know?
• Are there steps that you’re skipping or that aren’t fully explained?
• Do the steps make sense in consecutive order?

Creating your draft

The focus of your draft is to take the reader through the topics described in your outline, expanding on each topic with the detailed information your reader needs. When filling in content, you can use headers, paragraphs, procedures, lists, and callouts. Each of these conveys information in different ways. Each has its advantages and disadvantages.

Headers

Headings are like signposts: they organize content within your document. Headings also serve as destinations in documentation, letting readers jump to exactly the information they need.

When creating headers, keep the following tips in mind:
Be as brief, clear, and specific as possible.

Start with the most important information that readers need to know as close to the top of the page as possible.

Be consistent. Structure all of your headers similarly. If your document is a procedure for accomplishing a task, start every header with a verb. If you’re writing your document for a larger documentation set, match the style of headers in other documents.

Paragraphs

Paragraphs are groups of sentences that help readers understand context, purpose, and details of your document. Paragraphs give context about when to run a procedure, or offer details about how a procedure works. 

When writing paragraphs, give your readers the context they need to understand and act, but keep it short. Limit paragraphs to five sentences or fewer when possible.

Procedures

A procedure is a sequential set of actions a reader takes to achieve the 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. This serves as a kind of unit test for the documentation and prevents users from compounding any errors they may make.

Each step of the procedure should only cover one action. Your reader may be jumping between your documentation and your interface or the command line, and multiple actions in a single step can make it hard for your reader to follow along.

Lists

Lists allow you to group related information in a skimmable format. Lists include things like:

•     Lists of examples
•     Settings
•     Related topics

The longer a list grows, the less skimmable it becomes. If you find yourself listing more than ten items, consider dividing the list into smaller lists, broken up by headers and paragraphs.

Callouts

It might be something absolutely critical that a reader needs to know in order to be safe, or it might be some useful, related information that you want to highlight at that point in the document

Here are some examples of callouts and when to use them:

• Warning: Don’t take this action! Readers might be in danger, personal data might be at stake, or the system may suffer irreversible damage or loss.
• Caution: Proceed carefully. An action might have unexpected consequences.
• Note: Related information or a tip about what you’re currently reading.

Reserve callouts for important information your readers cannot afford to miss.

Writing for skimming

 There are two fundamental, paradoxical truths about readers of technical documentation:

•  Readers come to your documentation looking for information.
•  Readers read very little of what you write.

Note:
When readers view a page of content, research shows they typically skim the content in an “F” pattern, scanning in two horizontal lines across the top of the document for the title and subtitle, and then scanning down the page. They do not read every word on the page.

Writing for skimming

State your most important information first

Your title should summarize the goal of the document. Include any critical information in the first three paragraphs. If you’re writing a procedure, let the reader know what they will accomplish by the end of the document. If you’re writing something more conceptual, explain the importance of the concept you’re describing, and why knowing more about it will help your reader.

Break up large blocks of text

Long paragraphs are difficult to skim. If most of your writing is for print publications or academic papers, you’re probably more familiar with writing long-form essays. Unfortunately, most of your readers will skip over your page if they see a wall of text.

Writing for skimming

Break up long documents
It might be tempting to heap all of your content into a single document—but a single long document often tries to accomplish too many goals for too many different readers.

Writing for skimming

Strive for simplicity and clarity

It might be tempting to add information like the history of a project or the design considerations you’ve made on a system, but they don’t belong in a procedural document. Put the history, design theory, and commentary for a document in a separate place and title and format it appropriately.

Getting unstuck

Every writer gets stuck. Writing is difficult, creative work, and creative work is sometimes hard to sustain. It’s not because you’re bad at writing! Getting stuck is part of the writing process,

Let go of perfectionism
Your first draft of content shouldn’t be perfect—in fact, it doesn’t even have to be good. The goal of a first draft is to get all of the information down for your readers, not to craft a perfectly polished document ready for publication.

Ask for help
One of the best ways to get unstuck is to talk through your problem with another person. Ask someone to read what you’ve written so far and work through your outline of content with them. Talk through the issues that you’re having and where you’re stuck.

Getting unstuck

Highlight missing content
[TODO]

When you notice a gap in content—that important information is missing—make a note of it and keep working on the parts you’re sure you can fill in. You can fill in the gap during a later round of revision or writing.

Don’t get hung up on trying to write a document correctly and in order the first time through. Like code, writing is an iterative process. Write what you know, see what’s missing, research it, and write the new things you know.

Organizing documentation

There are three basic ways to organize your content:

• sequences
• hierarchies
• webs

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

The organizational structure you apply to your documentation is called its information architecture .

Sequences

Sequential structures are the most familiar to any reader. Any book you read is organized in sequential order—one page after another. Sequential ordering may be chronological, like the steps required to use an API, or maybe alphabetical, like an index or glossary. Sequential order requires you, the writer, to put the pages in the most effective order for your reader.

Hierarchies

A hierarchical structure is similar to a family tree or an organizational chart. Like a family tree, content has a parent/child relationship between pages. In a hierarchical structure, you start from one broad idea and narrow it down into more detailed and increasingly specific information. One main topic is supported by multiple related subtopics beneath it.

Webs

Webs are interconnected, non-hierarchical patterns of pages where each page links to one or more pages. This allows your user to decide how to view and organize your content. Wikipedia, for example, has a web organization. Each page is at the same level in the hierarchy and is linked to one or more pages in the set, allowing you to seamlessly read from one topic to the next, traversing any linked order you choose.