How to start writing documentation

Let’s say you’ve created a program or started an open source project, and now you’ve got people’s attention. They start asking more and more questions, taking more and more of your precious developer time to answer them. They fill your mailbox, sometimes even spam your IRC channel, often repeating the same questions. You know that you need to provide something in writing to help your users. But where to start ? What tools can you use? What output format do you choose? What topics do you need to cover?

Usually this is the time when people pull back and don’t actually start writing. After all, you’re a developer, not a tech writer, right? While this may be true, let’s not forget that documentation is an essential part of a project.

Start writing

I’m assuming you’re starting from scratch, so fire up your favorite editor and write your first lines of documentation. Call this first file README. Use plain text as the file format because it can be easily version controlled.

Use a markup language such as Reduction Where Texterestructured,
allows you to easily convert text to desired output formats, such as PDF or HTML, using pandoc, for example. As a bonus, most code hosting platforms scan README files and render most of the markup languages ​​correctly.

Quick start model

To describe the documentation, you can use the Markdown format template below. Start with a version ID or date. Use the ISO date format or write the name of the month so that people in other countries do not confuse the month with the day of the month.

READ ME v0.0 / 01 JUNE 2015

# Name of the project

## Introduction

Give your users an overview of the purpose and function of your project in a paragraph or two (at most). Because sometimes a picture is worth a thousand words, include screenshots where appropriate.

## Use

Provide a short code snippet (if applicable) or brief operating instructions

## Contributing

Provide instructions on how to participate in your project fixes.

## To help

Explain what communication channels are available for requesting help. The proven communication channels are mailing lists, IRC channels and forums. Also, be sure to tell your more senior users how and where to submit bugs or feature requests, possibly turning them into project participants.

## Installation

### Conditions

List everything your project needs to make it work as expected.

### Installation

Describe how to install your program. Be specific and give examples. Don’t assume your users know how clone from my github repository. Keep in mind that some of your users may be completely incompetent when it comes to system administration or software development.

### Configuration

After installing the software, the user may need to configure it. List the configuration options and explain how and where to set them.

## Credits

Sometimes also called Authors, here is the list of contributors to the project.

## Contact

People may want to contact you for a variety of reasons, ranging from DCMA takedown notices to questions about how to donate to your project. Provide contact information, such as an email address, and be aware that some countries may require certain information by law, such as a complete mailing address, website URL, and company name. the company.

## Licence

This project is licensed [insert license]. The license should be in a separate file called LICENSE, so don’t explain it in detail in your documentation. Also, don’t forget to specify the licenses for the libraries and third-party programs you are using.

Sometimes including a Table of Contents (TOC) at the beginning of the documentation makes sense, especially when your README file is longer than a few paragraphs. If you think the README file has grown too large, put some of the more detailed parts, such as the installation or configuration sections, in their own files.


Writing your first documentation doesn’t seem as difficult or time-consuming as you initially thought, does it? You now have a starting point that you can build on. Don’t forget to update your README to keep it up to date with your project’s development and new versions.


This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us at [email protected]

Sam D. Gomez