How to write good documentation (2023)

How to write good documentation (1)

[clique aqui para português]

I’m a weirdo. I know, that's a strange way to start an essay, but see — I'm the only person I know who always reads the instruction manual.

A while ago, I furnished my apartment and my bedside reading became a pile of manuals for house appliances. I enjoyed the refrigerator manual, but thought the ending was a little cold (…sorry).

Truth is, KitchenAid reader or not, nobody escapes from needing instructions in life and the experience is much more difficult if this document is incomplete or confused.

How to write good documentation (2)

In software development and tech, documentation has multiple functions:

  • Formalize processes and systems
  • Learn out loud
  • Help people answer their own questions

In all cases, both the writer and consumer benefit from the production of the material. If you want to participate in this knowledge exchange, here's a complete guide on how to write good documentation!

(Video) Writing effective documentation | Beth Aitman | #LeadDevBerlin

Before you start

Despite the parallel drawn earlier, making software documentation is much more complex than a device manual. That’s because there is no closed set of instructions that can be printed and never revised. Technology is constantly changing, and the most used systems are the most updated. Therefore, the most important documentation is the one that gets outdated faster.

That's nowhere close to encouraging, but it's remediable: most of the time, it's not the entire doc that is obsolete at once. It's the operational, technical details. So, one workaround is to separate the how from the why. How to use the system changes constantly, but why the system exists is a much more stable concept.

That was Etsy's idea when they did an experiment targeting “immutable” documentation. Following this concept to the letter involves other tools and making the process more complex, but we can extract a simple and very applicable lesson (TL; DR): whenever possible, avoid very specific details that can change. For example, instead of saying “We use the Roboto font”, you can give instructions to look for the project’s font in the <head> tag of the index.html file.

First steps

A blank page can be intimidating to the point of paralyzing even the most experienced writer. Here, we have the advantage of being able to start with a defined plan, without having to think too hard. I always follow three steps, in that order:

  • Collect reference materials
  • List content in macro topics
  • Add details and technical part

Before I started writing the Astro Readme (design system at my former employer), I first opened all the references I would use. Then, I listed the information I already knew the document would need to contain. At that moment, I didn’t care much about the order:

Astro Readme- Instructions for importing the dependency into your project
- How to add the sources
- How to run the project locally
- Where to view online documentation
- How to edit the documentation
- How to deploy the documentation
- Official support for React
- Known errors for troubleshooting

Now that the page is no longer blank, it's much easier to proceed by detailing each of these steps. Before that, however, let’s go into detail about the structure of this document.

Title and introduction

The question you must answer when writing the title and the first paragraph of your doc is: “What is this document for?”

Try to come up with a title that clearly states what the text is about. If that's not enough, the first paragraph serves as a support to understand if this document is where they'll find the information they're looking for.

Mobile Accessibility GuideThis document is a reference guide for recent discoveries and new practices that must be disseminated in our project to continuously improve the accessibility of the mobile app. Right now, our efforts are focused on VoiceOver (iOS) and TalkBack (Android) screen readers.

Steps or items

We can now go back to that information list we mapped in the first step. Now's a good time to try to organize these steps or items in the same order that the reader will need to refer to them. For instance, "Install" and then "Usage".

The best way to present the content may vary depending on the type of process to be described. Step-by-step instructions are clearer if numbered; actions with no defined order can be organized into topics; a less technical issue can be well explained with a FAQ, and so on. When in doubt, test more than one format before defining.

(Video) Writing technical documentation - tutorial with Confluence

Use very descriptive headings in each of them, to make it possible to quickly find the necessary information. This will also help you create a good index later.

Troubleshooting

In very technical docs, a "Troubleshooting" section can be especially useful for documenting known errors and obstacles and showing the way around them. It's important to keep this section up to date, as it's not uncommon to spend more time trying to fix bugs than actually developing.

Contact

In most cases, it's useful to leave contact info to answer questions and send suggestions by the end of the document. If you're writing a GitHub Readme, the contact section can also point to how and when to open an issue in the repository.

References

Including links to the materials used as a reference at the end of the doc is a good practice both for crediting authors and for readers who may be interested in diving deeper into those subjects.

Keep in mind

While creating this documentation, I suggest that you keep in mind some questions that help you cover as much territory as possible:

  • Who will read this documentation — and what's their technical level?

Will this doc be consumed by people within a company team, or by the general public in an open source project? It's necessary to adapt the technical level or detail according to the reader, keeping the text as didactic as possible. Remember that "obvious" is a relative concept; sometimes, we think anyone understands what we consider simple, but this is not always true (I'm looking at you, impostor syndrome).

  • Anticipate questions

That's basically an empathy exercise: try to anticipate any doubts that may arise throughout the text and answer them in the same place they appear.

  • Single source of truth

The “single source of truth” concept calls for a single location to be maintained as a source of consultation for all matters relating to a subject. It is easier to keep a single place updated, so this is a good practice to aim for.

  • Know when to stop

An unnecessarily long document is difficult to read and maintain. Try to discern how far you'll explain a topic within the doc or when it's time to link to a more specialized external tutorial. For more advanced people who may need more details, this is a way to point them in that direction without penalizing others with extra content.

  • Stay in scope

Still on the previous item, be as objective as possible. If a tangent process starts to get too detailed, it may be necessary to separate it into another document.

(Video) Writing technical documentation

  • Link, don’t replicate

Avoiding details that can easily change dramatically decreases the frequency with which the document will be outdated. If the shifting details can be found in a more up-to-date external source (for example, information about a third-party plugin or dependency), it is better to link to it than to replicate that content within your documentation.

Enriching details

So, you covered all the previous points and want to take it a step further? Here are some details that enrich the experience of those who consume your doc.

  • 1 reference = 1 link

Whenever you reference a concept or process, e.g. Markdown, find material on that subject and insert a link. Thus, a person who does not know exactly what that is or wants details can learn from a source you selected, which guarantees that you will be on the same page.

  • Illustrate

Screenshots, gifs, illustrations, graphics, memes… Choose the best way to illustrate the content and use as many figures as necessary to make the text more dynamic and didactic.

  • Information hierarchy

Those in contact with design are already familiar with this concept: the idea is to establish a visual hierarchy to facilitate quick understanding and localization of information. The most useful application here is to explore text formatting to create levels of title and subtitle (such as h1 to h6 headings in HTML), and thus to group macro and micro sets of information. We can also use bold, italics and even colors (like red in points of attention) to add intonation to the text, just as we would in voice speech.

  • Practical examples

Whenever possible, add an example of the process described to illustrate its application in practice. This will always make all the difference in message clarity.

All done, now what?

Hold the urge to click “Publish”! Now’s the time to groom and polish your doc. Bear with me, it's just a few more steps:

  • Read from beginning to end

When writing, it's normal to go back and forth several times and change paragraphs. Reading from beginning to end helps to review the cohesion of the text flow without interruption.

Time to drop a super important writing tip: the vast majority of people don’t read, they scan. Therefore, it's necessary to test the effectiveness of that information hierarchy, checking if it's possible to jump directly to a topic in the middle of the text and understand what is happening there. That’s what most people will do in your doc, no matter how good it is.

  • Edit

When proof reading, in addition to finding improvement points, you should also wipe down, summarize and cut redundant or unnecessary parts. Remember: people don't read everything, so less excess is more clarity.

(Video) What Are Good Documentation Practices (GDocP)? And Great Documentation Tips

  • Create the index

The index, or “Table of contents” as many call it, facilitates the preview of the content and also allows quick navigation. If the tool allows anchors (links that lead to points on the same page), use them.

  • Ask for reviews

Ask people familiar with the documented system to review it, so they can validate that you have covered all points and have not forgotten anything. Then ask unfamiliar people. This is the most important part of simulating how a new person will understand the documentation, and is usually where you'll get the most feedback.

  • Always update

After publishing the doc, it’s easy to forget about it forever. Technology documentation is never finished; the best practice is to elect a person or group responsible for maintaining it.

Another great trick for keeping docs updated is asking newcomers to contribute. They will read and use all those instructions for the first time, so that's a great opportunity to spot any outdated or missing info and improve them.

Final reminder

It's important to have well-written and updated documentation, but the software itself is even more important. We don’t want to get lost in detail and forget what our priority is, as the Agile manifesto preaches:

Working software over comprehensive documentation.

This priority is especially valid in the context of a closed company. But, of course, in a public or open source project, this motto has its caveats. After all, without documentation, it's very hard to understand third party code and impossible to contribute.

The final reminder is to always adapt the level of dedication to the documentation according to its context.

That's all for today and see you next time ❤

FAQs

What is the best way to write documentation? ›

Best Practices for Writing Documentation:
  1. Include a README file that contains. ...
  2. Allow issue tracker for others.
  3. Write an API documentation. ...
  4. Document your code.
  5. Apply coding conventions, such as file organization, comments, naming conventions, programming practices, etc.
  6. Include information for contributors.
29 Jun 2022

What are the 4 types of documentation? ›

The four kinds of documentation are:
  • learning-oriented tutorials.
  • goal-oriented how-to guides.
  • understanding-oriented discussions.
  • information-oriented reference material.

What are the characteristics of good documentation? ›

Characteristics of good documentation
  • All relevant information must be recorded.
  • All paper records must be legible, signed and dated.
  • Records must be contemporaneous, accurate and kept up to date.
  • Records must be written in plain English avoiding jargon.

What are the 3 rules of documentation? ›

Documentation should be:
  • Immediate. Managers should take notes right after an incident occurs. ...
  • Accurate and believable. When an outside observer (judge, jury or EEO investigator) is called to judge your side of the story, detailed observations add authenticity. ...
  • Agreed upon.
16 Jul 2015

What are the basic rules of documentation? ›

Be clear, legible, concise, contemporaneous, progressive and accurate. Include information about assessments, action taken, outcomes, reassessment processes (if necessary), risks, complications and changes.

What are examples of good documentation practices? ›

What is Good Documentation Practices?
  • Legal documents – business records, audit statements, and company policies.
  • Customer information – contact numbers, email addresses, and transaction history.
  • Procedural documents – standard operating procedures (SOPs), work instructions, and training documents.
13 Oct 2022

What is effective documentation? ›

Effective documentation collects all of the must-know information about a task, project, or team (from account logins to step-by-step instructions) in a centralized, organized place. No more digging through email or downloaded files for the latest information.

What are the examples of documentation? ›

Examples are user guides, white papers, online help, and quick-reference guides. Paper or hard-copy documentation has become less common. Documentation is often distributed via websites, software products, and other online applications.

How do you structure a document? ›

This article describes how to structure a document as follows:
  1. Use unique and descriptive page titles.
  2. Do not use color or spatial position to convey information.
  3. Add structure with headings.
  4. Format text with styles.
  5. Set the correct language for text.
30 Jun 2020

What is the main purpose of documentation? ›

Although there are many explicit purposes for creating a scientific or technical document, there are four general categories: to provide information, to give instructions, to persuade the reader, and to enact (or prohibit) something.

What are the five common types of documentation? ›

7. COMMON DOCUMENT TYPES
  • 7.1 Correspondence: Text Messages, E-mails, Letters, and Memos.
  • 7.2 Proposals.
  • 7.3 Progress Reports.
  • 7.4 Technical Descriptions and Definitions.
  • 7.5 Long Reports: Feasibility and Recommendation Reports.
  • 7.6 Lab Reports.
  • 7.7 Instructions.

How can I improve my documentation skills? ›

Improve Documentation in 5 Steps
  1. Minimize Passive Voice. Time for a quick grammar lesson: ...
  2. Use Catchy Headings and Bullet Points. People today are constantly inundated with content. ...
  3. Reduce Buzzwords and Acronyms. ...
  4. Invest in Visual Content. ...
  5. Organize Your Documents Appropriately.
7 May 2022

What is document quality? ›

Quality Documentation means the quality manuals, quality plans, quality procedures, inspection and test plans, work instructions or like documentation, as appropriate, which describe and define a Quality Management System.

What six characteristics should all documents have? ›

Good docs have (at least) six key characteristics:
  • Findable.
  • Accessible. Legal Accessibility. Language Accessibility.
  • Scannable.
  • Searchable.
  • Timely.
  • Complete.
5 Nov 2021

Why proper documentation is important? ›

Documentation is a great tool in protecting against lawsuits and complaints. Documentation help ensure consent and expectations. It helps to tell the narrative for decisions made, and how yourself or the client responded to different situations.

How many golden rules of documentation are there? ›

CNA Duties: Eleven Golden Rules of Documentation.

What is the cardinal rule of documentation? ›

A cardinal rule of documentation is to avoid listing negatives when charting. Document what you see, not what you don't see.

Is documentation a skill? ›

Whether you're a software engineer documenting code or a medical doctor documenting patient records, strong documentation skills are essential for any profession. Documentation not only helps others understand your work, but it can also be a valuable reference for yourself or others in the future.

What makes a good progress note? ›

Write down what was heard or seen or witnessed, what caused it, who initiated it. Concise - Use fewer words to convey the message. Relevant - Get to the point quickly. Well written - Sentence structure, spelling, and legible handwriting is important.

What are the goals of a good program documentation? ›

Advantages of Documentation
  • Keeps track of all parts of a software or program.
  • Maintenance is easier.
  • Programmers other than the developer can understand all aspects of software.
  • Improves overall quality of the software.
  • Assists in user training.

Which date format is good documentation practices? ›

1.4 The preferred format for the handwritten date on documents is the format: 2 digit day, three character month, 4 digit year.

Why is it important for nurses to document? ›

Nursing documentation is essential for good clinical communication. Appropriate documentation provides an accurate reflection of nursing assessments, changes in clinical state, care provided and pertinent patient information to support the multidisciplinary team to deliver great care.

What does the C mean in CGMP? ›

Accordingly, the "C" in CGMP stands for "current," requiring companies to use technologies and systems that are up-to-date in order to comply with the regulations.

What style of writing is documentation? ›

A documentation style is a standard approach to the citation of sources that the author of a paper has consulted, abstracted, or quoted from. It prescribes methods for citing references within the text, providing a list of works cited at the end of the paper, and even formatting headings and margins.

What is complete documentation? ›

Complete Documentation means documentation and other detailed written support which identifies with specificity the basis and the charges which are subject to the Bona Fide Dispute, the Service interruption credit or other credit to which Customer reasonably believes itself entitled, and the amounts being withheld by ...

How do you document tasks? ›

How to Document Processes
  1. Step 1: Identify and Name the Process. ...
  2. Step 2: Define the Process Scope. ...
  3. Step 3: Explain the Process Boundaries. ...
  4. Step 4: Identify the Process Outputs. ...
  5. Step 5: Identify the Process Inputs. ...
  6. Step 6: Brainstorm the Process Steps. ...
  7. Step 7: Organize the Steps Sequentially. ...
  8. Step 8: Describe who is Involved.

What are 3 types of documents? ›

Types of documents
  • HTML files.
  • Microsoft PowerPoint presentations.
  • Microsoft Word documents.
  • Plain text documents.
  • PDFs.

What are the methods of documentation? ›

Methods of Documentation
  • DAR (data, action, response)
  • APIE (assessment, plan, intervention, evaluation)
  • SOAP (subjective, objective, assessment, plan) and its derivatives including.
  • SOAPIE (subjective, objective, assessment, plan, intervention, evaluation).

What is the format of documentation? ›

A documentation style is a standard approach to the citation of sources that the author of a paper has consulted, abstracted, or quoted from. It prescribes methods for citing references within the text, providing a list of works cited at the end of the paper, and even formatting headings and margins.

What is effective documentation? ›

Effective documentation collects all of the must-know information about a task, project, or team (from account logins to step-by-step instructions) in a centralized, organized place. No more digging through email or downloaded files for the latest information.

How do you structure a document? ›

This article describes how to structure a document as follows:
  1. Use unique and descriptive page titles.
  2. Do not use color or spatial position to convey information.
  3. Add structure with headings.
  4. Format text with styles.
  5. Set the correct language for text.
30 Jun 2020

What are the examples of documentation? ›

Examples are user guides, white papers, online help, and quick-reference guides. Paper or hard-copy documentation has become less common. Documentation is often distributed via websites, software products, and other online applications.

How do you write a professional document? ›

Here are some tips for writing professional documents.
  1. Practice! ...
  2. Make a plan for improvement. ...
  3. Make sure you focus on the purpose for the document. ...
  4. Understand your audience. ...
  5. Organize your document for understanding. ...
  6. Ensure a professional appearance. ...
  7. Ensure perfect punctuation, grammar, and spelling. ...
  8. Watch your tone.

What is the most common document format? ›

PDF. The PDF document file is a Portable Document Format by Adobe that has become the most prevalent file format used on the web today.

What is the main purpose of documentation? ›

Although there are many explicit purposes for creating a scientific or technical document, there are four general categories: to provide information, to give instructions, to persuade the reader, and to enact (or prohibit) something.

Why proper documentation is important? ›

Documentation is a great tool in protecting against lawsuits and complaints. Documentation help ensure consent and expectations. It helps to tell the narrative for decisions made, and how yourself or the client responded to different situations.

What is complete documentation? ›

Complete Documentation means documentation and other detailed written support which identifies with specificity the basis and the charges which are subject to the Bona Fide Dispute, the Service interruption credit or other credit to which Customer reasonably believes itself entitled, and the amounts being withheld by ...

What is process documentation? ›

Process documentation is the act of capturing or documenting all of the steps in a particular task. Ideally, it should happen in real time. As employees perform a task, they document each step they take.

What is a documentation system? ›

Documentation systems are tools by which one participant in an academic discipline, or field of study, acknowledges the work of another. Using one is much more than a professional courtesy: it is a requirement.

Why do documents need to be structured? ›

Structured documentation makes it easier for the user to grasp information. Further, it is also convenient to directly go to the section of required information if the document is structured in a standardized way. It can save a considerable amount of time for the user.

What are the five common types of documentation? ›

7. COMMON DOCUMENT TYPES
  • 7.1 Correspondence: Text Messages, E-mails, Letters, and Memos.
  • 7.2 Proposals.
  • 7.3 Progress Reports.
  • 7.4 Technical Descriptions and Definitions.
  • 7.5 Long Reports: Feasibility and Recommendation Reports.
  • 7.6 Lab Reports.
  • 7.7 Instructions.

What are 3 types of documents? ›

Types of documents
  • HTML files.
  • Microsoft PowerPoint presentations.
  • Microsoft Word documents.
  • Plain text documents.
  • PDFs.

Videos

1. Q&A -- How to Properly Document Your Work | Very Important Skill !!
(Information Technology Q & A Show)
2. Kat Christofer - How to write good documentation
(WooCommerce)
3. TALK / Meredydd Luff / Writing Good Documentation for Developers
(PyCon US)
4. 5 tips for good documentation in GMP and GLP environments
(CRAMbridge)
5. CppCon 2017: Robert Ramey “How to Write Effective Documentation for C++ Libraries...”
(CppCon)
6. What is a Design Doc: Software Engineering Best Practice #1
(TechLead)
Top Articles
Latest Posts
Article information

Author: Nathanial Hackett

Last Updated: 01/06/2023

Views: 5877

Rating: 4.1 / 5 (52 voted)

Reviews: 83% of readers found this page helpful

Author information

Name: Nathanial Hackett

Birthday: 1997-10-09

Address: Apt. 935 264 Abshire Canyon, South Nerissachester, NM 01800

Phone: +9752624861224

Job: Forward Technology Assistant

Hobby: Listening to music, Shopping, Vacation, Baton twirling, Flower arranging, Blacksmithing, Do it yourself

Introduction: My name is Nathanial Hackett, I am a lovely, curious, smiling, lively, thoughtful, courageous, lively person who loves writing and wants to share my knowledge and understanding with you.