Author: Write Documentation That Actually Gets Read

With your documentation plan in place, now comes the part where the magic (and the writing) happens.

This guide walks you through considerations, tips, tricks, and best practices to write product documentation, onboarding guides, and other types of content that describe, aka document, something.

You will find this guide useful no matter what tools you’re using. Clear, well-presented, useful, and easy-to-maintain content is tool-independent. That said, some tools, like Confluence, make your job easier because of how they integrate project management, support, and AI tools into a single suite.

How Do I Start Writing?

You obviously know what you’re documenting because you have prepared your plan. But then you sit down and don’t know where to start.

To overcome writer’s block, you can:

1. Simply write down what you know.
   You end up with drafts, bits, and pieces. It may be incoherent but it’s ok.

2. Look at the subject matter from the reader’s point of view.

   • what they need to know

   • what they need to know first

Your goal as a writer is to match your knowledge with users' needs. Writing things down in almost a stream of consciousness mode will later give you the opportunity to arrange and rearrange your raw knowledge and map it to the eventual user’s journey.

The structure of your article(s) will begin to emerge and you will already have content that you can move around. The need to connect the bits you wrote will make it easier to find the gaps that exist in your knowledge.

Dismantling existing content

Many writers box themselves in within the existing documentation structure. Do not be one of them. You are adding new content for new features or policies. You may realize that some elements feel out of place now, that the heading no longer works, etc. Your role as a writer is to make sure that documentation always works for the most up-to-date version of the product, etc. – not for last year’s iteration.

Are You Writing Alone?

Documentation is a collaborative effort. You write, an engineer might share their subject-matter-expert knowledge with you, somebody else might prepare your visuals – a video, a diagram…

Sometimes, you have to rely on someone else’s knowledge to draft a new article with you taking care of beautifying it, taking care of the formatting and publishing. By the way, that’s no reason for shame and, more often than not, everybody wins. Having a subject matter expert writing the initial draft is a lot faster than an attempted knowledge transfer and a constant back and forth caused by misunderstandings.

If you’re working with team members who are not writers, ensure they know how to use the tool and that they have access

If you are really the lone writer, always ask for a review by another pair of eyes and use a spellchecker or an AI tool that you trust (and that is approved by your company in terms of privacy and security.

Pyramid Schemes

Once you have written down all that you know about the subject matter of what you are documenting, you will start organizing information. A page is not just a collection of random thoughts unified by a topic. Information needs a structure to flow. Broadly speaking, usually there’s an introduction, main topic, conclusion, or directions on where to go next.

• Introduce the main topic, set expectations, define the content of the page, and… provide the food for SEO and search in general .

  • On this page/in this article, you will learn how to arrange information on a documentation page.

  • It can also be a disclaimer, for example, that the page is an early access feature’s documentation, or that content is only for admins.

• For the main body of content, apply the so-called Pyramid Principle. Put the important information at the top, then elaborate, add details, exceptions, etc. For example:
  overview → description of main features → individual features' docs → troubleshooting.

  • On more complex issues, or when dealing with an audience that is not exactly savvy in the subject matter, you may insert a reassuring bit at the end:
    You should now be able to do this-and-that. We suggest that you do THIS as the next step.

You can scale the pyramid principle up to the entire hierarchical section of pages. Imagine the following tree:

• overview

  • description of main features

  • individual features' docs

  • troubleshooting

In product documentation, you may need to start with background information, such as prerequisites to tell users what they need to do or know before they can proceed. Always think about the information flow from the user’s perspective – what they need to know first. That’s where an inverted pyramid (funnel) is used.

Pyramid vs inverted pyramid (funnel)

Information Elements

When you think about it, you need to deliver just the following four basic types of information:

• Facts – descriptions, definitions, etc.

• Expectations – prerequisites, considerations (prior and/or contextual knowledge)

• Procedures – processes including outcomes

• Relationships among the above

You need to express everything using mostly text. Of course, you should also use images and videos but they still need description or a script. And for some type of information, text is a superior format.

What is text? Written text delivers information expressed through characters. What is often ignored, though, is the ability of text’s structure and formatting to support that information. Structured text is a thing and your goal will be to match the formatting to the type of information you’re trying to convey in text.

Structured text itself carries information, it conveys meaning. Which is why poorly chosen formatting styles may confuse users. These pairings – formatting of the text/meaning – are often referred to as information elements.

Example:

• Numbered list (ordered list):
  Conveys the meaning that the order in which individual items are arranged is important. It tells the user they should perform the actions in the specific order (process, procedure).

• Regular lists of items:
  Items are just listed, with no hierarchy. Just ensure that the category/level of the items on the list is the same.

• /⚠️ Warning emojis or red/orange box signal critical/important information and force the reader to pay attention before they read the first word.

The messaging may be more subtle and you can define information elements in your style guide. In the following example, we’re using bold text to convey the meaning that whatever is bold is actually a UI element of the same name.

Make the page work visually

Once your content is solid, formatting and layout can help it shine :

• Help people navigate the page and use headings that actually say something. Headings (subheadings) on the page organize information into logical chunks.

• Make the page visually appealing and ensure that the important information on the page is easy to find .

• Images , videos, charts , diagrams , tables . You can add them all but, at the same time, try to avoid clutter and keep in mind that a lot of graphic elements make the page longer and difficult to navigate.

• Using columns to lay out sections enables you to group related content visually, and focus readers' attention on what matters most. In Confluence, use layouts to divide a page into standalone content chunks.

Page Length

One of the best documentation best practices? Don’t overwhelm your readers.

There are three ways to overwhelm the users:

• empty pages

• extremely short pages with just a couple of sentences that lead users to engage in a clickathon

• extremely long pages

Now, out of those three, you should only avoid empty pages. See, for a certain type of content, super-short and super-long pages might be the best solution. Under normal circumstances, however, you should always try to strike a balance. Let content and context be your guide.

Short page example – error codes

Something goes wrong, your system generates an error code such as W123456. What will a user do? They copy the code from the UI and search for it in your documentation.

It makes perfect sense to apply the one error code / message = one page approach.

Long page example – a complex procedure

A procedure is a single flow of steps the user must perform in a single (uninterrupted) effort to accomplish a clearly defined goal. Typically, it’s a really complex procedure such as setting up a hybrid Linux/Mainframe environment or navigating an internal procurement process to request a new keyboard 😉.

Benefits of reasonably sized pages

Long pages may make the page tree structure look tidy both in your content management system (CMS) and in the documentation center. But the truth is they rarely help your readers. In fact, they often bury useful info under a pile of headers, tables, and tiny scrollbars.

Here’s why breaking up long pages makes sense:

• Clarity and focus: People don’t read the way we wish they would. They scan. They scroll. They bounce. Smaller pages help readers stay focused and make it easier to understand one concept at a time.

• Better search results: Each page gets its own search hit. That means more relevant results and less Ctrl+F panic inside a giant blob of text.

• Cleaner collaboration: Shorter pages reduce overlap when multiple people are editing. Access permissions are easier to manage, and comments, or feedback in general, get more focused.

• Faster publishing: Smaller, topic-specific pages are easier to update and publish. You’re not holding up changes because someone else is still writing halfway down the same doc.

Chunking, de-chunking, and expandables

Let’s get the terminology clear:

• chunking – merging of short pages into one
  Example: You have 5 pages, each with a one-liner definition of a single term.

• de-chunking – breaking up a long page into reasonably sized pages under a single parent.

• expand – use an expandable box to hide a certain type of information from the direct view but give users an option to reveal the section if they need to.
  A typical example is a list of ten or more items that would make the page unnecessarily long.

  • list of languages that you support

  • list of prohibited items

Here are some tips that should help you decide on how to find the break / merge point.

• Check to see if the page includes more than one major topic . This can happen over time, as new content is added.

• Take a look at support cases, comments, and other feedback to see what information people aren't finding in their searches. This can identify pages that may have once been useful, but might now need some restructuring.

• If you need to scroll just to get to the end of the table of contents, then it’s time to break up the page to promote easier navigation and skimming.

If Content Is King, Context Is Emperor

Every article in your documentation exists in the context of others. An article can help on its own and answer a user’s question. And that’s great. To advance users' knowledge, you need to present information in context. This applies in product documentation guides just as it applies to onboarding docs for your HR team.

In other words, always present your new content in the context of the existing content to help users truly understand what they’re doing. You need to show relationships among pages, processes, components, etc.

Your two best friends are:

• Navigation tree, also called content tree:
  The right placement of a page in the tree immediately provides contextual data to the reader.

  • It shows the hierarchical relationship among the pages.

  • It allows users to discover the unknown unknowns. Sometimes your audience doesn’t really know what they’re looking for. An organized tree also promotes product/feature discovery.

• Links to other pages:
  Here’s where the size of the pages matters – linking to a specific page is always easier than linking to a subheading on a page. It applies both to accessing the actual content and to the link/page management.

Writing Guidance, Not Control

To readers, documentation should appear as if written by a single person. Pages should share the same look and feel.

There are many tools and methods for guiding uniformity of your documentation. Many are useful. Some are helpful. If you resent them, please, make this one mandatory – spellchecker 🙂

Some teams have experience with traditional documentation writing apps that have defined content types or templates that tightly control what team members can write on a page.

You can guide the creators of your documentation using the template by adding helpful placeholder text , but you won’t find the full control seen in other tools. For good reason.

Instead of limiting contributors, use templates to empower them to share knowledge in a way that works for your organization. By standardizing article formats for certain types of content early on, you're laying the foundation for a scalable, sustainable documentation management process. One that supports consistency across every stage of the documentation life cycle, without slowing your team down.

Recommended reading

Google’s crash course on technical writing is aimed at technical/product documentation writers. However, it is easy to read even for non-technical users and contains practical advice that you can apply to any documentation writing.

https://developers.google.com/tech-writing/overview