How to start writing documentation

A template for starting project documentation

Image of typewriter keys
Image credits : 

Original photo by mpclemens. Modified by Rikki Endsley. CC BY-SA 2.0

Get the newsletter

Join the 85,000 open source advocates who receive our giveaway alerts and article roundups.

Let's say you've created a program or launched an open source project, and now you have people's attention. They start to ask more and more questions, taking more and more of your precious developer time to answer. 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 should you start? What tools can you use? What output format do you choose? What subjects must you cover?

Usually this is the point at which people pull out and don't actually begin writing. After all, you're a developer—not a technical writer—right? Although that may be true, let's not forget that documentation is an essential part of a project.

Start writing

I assume you're beginning from scratch, so fire up your favorite editor and write your first lines of documentation. Call that first file README. Use plain text as a file format because it can be version controlled easily.

Using a markup language such as Markdown or reStructuredText,
lets you easily convert the text into the desired output formats, such as PDF or HTML, using pandoc, for example. As a bonus, most code hosting platforms parse README files and render most markup languages properly.

Quickstart template

To outline the documentation, you can use the markdown-formatted template below. Start with a version identifier or a date. Use the ISO date format or write out the name of the month so people in other countries don't confuse the month and day of month.

README v0.0 / 01 JUNE 2015

# Project name

## 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 when appropriate.

## Usage

Provide a short code snippet (if applicable), or short usage instructions

## Contributing

Give instructions on how to participate in your project patches.

## Help

Explain which communication channels are available to request help. Communication channels with a proven track record are mailing lists, IRC channels, and forums. Also be sure to tell your more experienced users how and where to submit bugs or feature requests, possibly turning them into project participants.

## Installation

### Requirements

List anything your project requires in order to work as expected.

### Installation

Describe how to install your program. Be precise and give examples. Don't assume your users know how to clone from my github repo. Keep in mind that some of your users may be completely unskilled in system administration or software development.

### Configuration

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

## Credits

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

## Contact

People may want to reach out to you for various reasons, ranging from DCMA take down notices to questions about how to donate to your project. Provide contact information, such as an email address, and keep in mind that some countries may require certain information by law, such as a full postal address, website URL, and company name.

## License

This project is licensed under [insert license]. The license should be in a separate file called LICENSE, so don't explain it in detail within your documentation. Also, don't forget to specify licenses of third-party libraries and programs you use.

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

Conclusion

Writing your first documentation doesn't seem as hard or or time-consuming as you initially thought, does it? Now you have a starting point on which you can build. Don't forget to update your README to keep it current with your project's development and new releases.

Doc
Dish

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 open@opensource.com.

About the author

Jan Niggemann
Jan Niggemann - Jan Niggemann is a project manager and ERP administrator with a focus on process management in Heilbronn, Germany. He started using Linux in 1998 and quickly became an open source enthusiast. Besides being a family guy, he's a member of the redmine and Obnam projects.