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.
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.
2 Comments