How to Prepare Documentation for a Project

Last Updated: April 9, 2019

This wikiHow teaches you how to write documentation for an open source project. This documentation is usually referred to as a README file. The README is a text or HTML document that contains important information for both users and developers about your project. ^{[1]
X
Research source}

Steps

1
Write the title for your project. When writing a README for your project, the first thing you should include is the project title. Along with the title, you should also include the latest version number and the date it was last updated.
2
Write a description of your project. The next thing you need to include in your README is a brief description of your project. Explain what the project does, why it exists, and what problems it solves. You can also include any special features, screenshots, code style, tech or framework used, or anything else that would be helpful to users and developers.^{[2]
X
Research source}

Advertisement
3
Explain any requirements your project has. If your project needs any special requirements in order to run properly, be sure to list those requirements and instructions, or a link to instructions on how to install them.
4
Include a sample of the code. Provide a clear and concise example of what your project is used for. The code should be easy for developers to figure out, and the API should be clearly visible.
5
Provide installation instructions. Explain to users how to get your software up and running in a step-by-step format. Your instructions should be as clear as possible. Assume your users have no knowledge of software development or system administration.
6
Explain how to use the software. Tell people how to get the most out of your software. Provide step-by-step instructions on how to use your software as well as different configuration options and how to set them.
7
Tell users how to get technical assistance. Provides links to any mailing lists, IRC channels, or community forums that users can turn to for technical assistance. Also let more experienced users know where to submit bugs and ideas to make the project better.^{[3]
X
Research source}
- If you find you are getting a lot of the same questions from different users, you may want to include an FAQ (frequently asked questions) as part of your project documentation.
8
Explain how to contribute. If you are working on an open-source project, let your users know how they can contribute to your project. Explain any standards you have and provide some guidelines to potential contributors.
9
List the credits. Always give credit where credit is due. Be sure to list the names all contributors, as well as links to any third-party libraries or programs you may have used. Include links to any inspiration you may have had while building your project.
10
Provide your contact information. People may want to contact you for any number of reasons. Be sure to provide a valid email address that people can use to contact you.
- Some countries may require additional information, such as a postal address, or company name by law.
11
Provide license information. It's important for users to know how your project is being licensed. There are plenty of standard licenses around the web that you can use. Explain what license your project is using, as well as the licenses of any third-party libraries or programs you might use.
- You don't need to explain the entire license in your documentations. Just let users know what license your project is using, and provide a link to the full license information.
12
List all versions of the project. Be sure to create a list of all previous versions of your project and write a brief description of what edits you made for each version.