Dos and Don'ts in technical writing

Working in distributed cross-functional teams on different projects gave me the understanding that a content written by different team members—devs, QA, architects, etc.— in different periods of time most likely looks like a total mess.

Below is my list of recommendations to apply to the project documentation to make it look professional, clear, and concise.

It might look obvious from the first sight. However, I put it here, so you can copy and share it with your tech team folks, so that they all could be on the same page with you when it comes to a project documentation.

Most of them are related to the Atlassian Confluence pages, but the general logic can be applied to any documentation tool and documentation kind you'd like to tackle.

So here we go!

---

Do's:

• Add periods at the end of each sentence.

• Add colons after a word if the following text is organized as a list.

• Start the first list item always with a capital letter in a bullet or numbered list.

• Use a numbered list only when it is needed to emphasize on the steps order. In other cases, use bullet lists.

• Decide whether to put a period at the end of any bullet and numbered list item. I recommend putting the period there because if an item consists of more than one sentence, you must put the period between the sentences. That’s why the period should also be put at the end of the second sentence (for consistency and accuracy).

• Use tables where proper through the text—tables help organize the content in a well-structured and user-friendly way and reduce overall page size so that not to frighten a reader with a lot of text, especially when it is needed to scroll down a page several times.

• Use the Expand macro to make big content chunks collapsible. The justification here is the same as for the tables' use.

• When working in Confluence, always use proper heading order starting from Heading 1 and further descending. Don’t use Heading 2 or Heading 3 as the first heading on a page. Moreover, don’t skip intermediate headers. For example, use the pattern Heading 1 → Heading 2 → Heading 3 and don’t use Heading 1 → Heading 3 or Heading 2 → Heading 4.

• For a page title, capitalize all words except for the articles and the prepositions.

• For a page heading, capitalize only the first word, regardless of the heading level.

• Try to give specific names to all links on a page if/where it’s possible.

• Use Children Display and Table of Contents macros everywhere on the pages, or not use it at all (for consistency throughout your wiki space).

• Apply Responsive wiki page style for all the tables on your wiki pages by default.

• Create page titles and headings as short as possible. Skip the articles (a/an/the) and restructure the title/heading to exclude excessive prepositions if possible. For example, shorten the page title Working on an internal documentation of a project in Confluence to the Working on project internal documentation in Confluence.

---

Don'ts:

• Avoid using the same duplicating word(s) in the titles of child pages. For example, your parent page is Super-duper Team Member Onboarding and all the included child pages should have unique titles like Checklists, Calendars, etc., and not the titles like Super-duper Team Member Onboarding: Checklists, Super-duper Team Member Onboarding: Calendars.

• Don’t put extra white spaces on a page to separate different content chunks from each other, or just in case. Space on a page increases its length and makes it difficult to read the whole content.

• Avoid excessive page nesting if possible.

• Avoid the same content duplication on different wiki pages.

• Don't apply any sorting options for the Children Display macro if it's placed on a parent page—this way, child pages will display on the 'parent' in the same order as they display on the left-side navigation pane.

• Don't make page headers as links—put required links in the description below.

• If possible, try to avoid putting a single sentence under a separate unique Header. (A header with a single sentence looks quite strange on a page—it may seem like a part of the content is missing there.)

• Avoid using a bullet or numbered list if it consists of less than two items.

You can always add the best tech writing practices from your perspective.

Enjoy!