Documentation is important. All of us have experienced the challenge of finding the documentation we need, and most of us have struggled to try and write well.  But it need not be so difficult.

Following is an easy approach plus a few guidelines that will help to produce & maintain real, usable, documentation easily.

The Easy Way to Write Documentation

The easiest way to write documentation, is to start a page quickly and get a couple of sections and basic bullet points down. This will take only 15-30 minutes and captures much of the value. Finish for now.

Over the next day, you’ll likely think of a couple of points you missed.  Take 15 minutes to add those in, and wrap the content up.

Once you’ve done this a few times, you’ll find you are capturing the most useful content quickly, and fairly comprehensively; and that doing this takes little difficulty.

It is always possible to spend longer and capture more detail, but much of the value for most audiences is in the big picture. So you do not need to capture the world now. Over time, you and your team, can always return to add more.

Documentation should be a live, as-you-go process which the entire team contributes to.

The best time to write documentation is when you are working on that area; but don’t hesitate to back-fill gaps as you find them. Frequent small improvements make a big difference.

Principles

Many people struggle to know how to start writing a page, or to know what goals it should fulfill. A few simple principles will help.

Within the Page

Within a single page, a few basics are key:

1. Target the audience.
   • Think of the audience who will need to read your documentation. They probably have some general technical knowledge, but don’t know your specific feature or acronyms. Express your writing so they can understand.
2. Identify the page well.
   • For example, give the page a good title; and provide a concise statement of what the page is about at the top. This is because the first thing readers need, are to find the page and determine whether it relates to their question.
3. Front-load an overview.
   • A concise overview enables audiences to understand what something is, and the basic ideas of how it should work. The overview is often the most useful useful and valuable part of the documentation, for the majority of audiences, and should be presented as the first section in the page.
4. Combine brief narrative with bullet points.
   • Bullet points are faster to read & write and express clear facts.
5. Link to related content.
   • Links are hugely important in Wiki and web content. They show readers what content is specifically related and important, and enable an audience to rapidly explore connected pages & topics to understand the area.

Organizing Content within the Wiki

When organizing pages within a Confluence hierarchy, keep these principles in mind to help audiences find & navigate content:

1. Structure the hierarchy by Topic or Category.
   • Categories can be: business function/ audience, software component, feature, lifecycle status, etc.
   • Note that some pages can benefit from organizing their child content with more than one dimension. For example, existing features could be grouped by component, while planned features could be grouped under status.
2. Front-load useful information.
   • Always ensure that key information such as Overview, Status and Navigation are available on the upper pages;
     do not push these down to child pages.
3. Manage the number of children; but balance this against cohesiveness and front-loading information.
4. Keep content cohesive.
5. Use ‘aspect pages’ or mentions where topics interact across the hierarchy.
   • Placing a contextual mention or aspect page in the other hierarchy, makes the topic clearly visible from the perspective of that audience/ business function/ component.

Writing a Page – 7 Key Steps

Here are seven simple steps to help you write a useful page:

Title for searchability	Title the page by what the audience might be looking for. Use commonly-understood terminology.
‘Statement of Purpose’ at the top also, Status (if not current & active)	Start the page with 1-2 sentences on what the page is about. Write from the perspective of a reader who is not immediately familiar with the topic, using standard Business English. This will place it into context for the reader, and enable them to easily understand whether the page is relevant to them.
Contents	If you’ve got more than a couple of sections of content, add a ‘Table of Contents’ macro before the Overview.
‘Overview’ section	Write a couple of paragraphs of narrative and/or bullet points, stating the most important points about the topic. Use an H1 or H2 heading. A clear Overview is often the most important part of the documentation. Key aspects to cover in the Overview include: Purpose and context – what is the purpose of the component/ feature/ topic, and what wider context this exists in. Lifecycle – what is its lifecycle? Often a brief statement, but for more complex lifecycles state where it comes from/ is created and where it goes to/ is consumed. Interactions – what else does it interact with. sometimes Technical Underpinnings – less important to understanding what something is, but if there’s space in the Overview we can add a simple point or two.
Brief Narrative + Bullet Points	Use a little narrative first, then get straight into the bullet points. Bullet points are preferable to  narrative because: They’re fast & easy to write They’re easier to read They avoid wasting time faffing around with all the connecting words needed for narrative writing.
Detail Sections (where applicable)	The Overview intends to convey “what it is” in 10-15 seconds. Detail beyond this, should be structured into one or more Detail sections. If the page is getting longer than two screen-heights or the detail would be useful to less than 20% of the audience or page views (eg. detailed trouble-shooting or technical procedures), consider pushing the less-relevant detail sections down to a child page.
Child Page/ Subcategory Navigation (where applicable)	Add a “Section” heading and use a Confluence ‘Children’ macro with depth=1 or 2, to show child pages automatically. This front-load navigation on the page; and will be self-maintaining, unlike manually curated links.
‘See Also’ links	Add a ‘See Also’ heading and bullet-point a few relevant links. These may be useful lateral links, or particularly important child or parent pages. These enable lateral navigation across hierarchy boundaries, and greatly improve the ability of readers to explore & understand a topic.

 

Organizing Content – Another 7 Steps

While the number is purely coincidental, another seven basic steps will help you organize content:

Organize the Top Level	The top level is most important, as it where many users start navigating. Lay out a clear structure that addresses business functions, audiences and technical structure in a meaningful way.
Structure the hierarchy by Topic or Category	Categories can be: business function/ audience, software component, feature, lifecycle status, etc. If you have a few child topics, these can be listed directly. If you have many child topics, group some or all of them under category subpages.
Front-load useful information	Always ensure that key information such as Overview, Status etc are available on the upper pages; do not push these down to child pages. The corollary of this is, as a page gets large, to push infrequently-used content down.
Front-load navigation	Category pages should offer a prominent navigation section. The Confluence ‘Children’ macro with depth=1 or depth=2 is great to build quick & easy navigation for readers. While it’s good to offer the most important child pages/ resources as curated links, prefer to supplement this with a ‘Children’ macro for most navigation as it’s self-maintaining.
Manage the number of children	But balance this against the benefits of cohesiveness and front-loading information. A guideline of five to eight is children is ideal, but should be balanced against other factors. It is very reasonable to bend the guideline where good reasons exist. It’s common for a top-level page to have 12-15 children, or a major category landing page where numerous facets converge to have 10-14 children.
Keep content cohesive	Balance this with other factors, but it’s beneficial to keep the most useful aspects of a topic together. Do consider this in terms of the audience & how often content will be used. Different audiences or infrequently-used content may provide good reasons to split something out.
Topics interacting across the hierarchy	Where topics interact across the hierarchy, create an ‘Aspect page’ or mention in that part of the hierarchy. For a small or modest interaction: bidirectional links and either a brief bullet point or a section in the page, might suffice. For a major interaction: create an ‘Aspect page’ in the other hierarchy, presenting that aspect of the topic. Link this aspect page and the main topic bidirectionally.

How to Design a Hierarchy

In a Wiki hierarchy, content should be organized by key factors including organizational purpose, software component, feature area, and specific feature.

The appropriate categorization approach and order in which levels can best be structured, may vary somewhat according to the needs of the particular organization & software product.

In recent roles I have had success with the hierarchies similar to the following:

1. Business Function/ Audience
   • eg. Technical Reference, Developer Guides, Testing, Releasing, Support etc.
   • Note that we split ‘technical/ architecture reference’ materials from all ‘developer practice/ process how-to’. This enabled a useful separation between actionable guidance & tutorial material, and the ‘why is it designed this way’ reference material.
2. Software Component
3. Feature Area
4. Specific Features
   • Overview, major functionalities, relationships & interactions with other components
5. Subordinate Details (if needed).

Categorizing Child Pages

When considering how to subdivide a lower-level Category Page, we have often found some or all of the following categories useful to use:

• Major Specific Elements — some key child topics, or those that don’t fit well in a general bucket, could be candidates to be direct children.
• Technical Reference
• Processes/ Practices Guide
• Work Underway
• Ideals and Proposals — problems, ideas and proposed enhancements

Of course as these divisions grow larger, they may eventually need to be sub-categorized themselves. This is the essence of building a content hierarchy.

Conclusion

Documentation is a common pain-point for developers. However much of the value for readers can come from simple elements, such as a simple overview, clear bullet points and basic categorization.

Using these techniques to write and organize content will enable more useful documentation to be created, and less struggle to write it.

Good luck and happy Wiki’ing!

References

• https://opensource.com/article/17/1/tips-using-wiki-documentation
• https://developers.google.com/tech-writing/one/documents
• https://www.techsmith.com/blog/awesome-user-documentation/