README
So, you finally have time to work on that program you’ve been setting aside for weeks. You open your project folder, only to find yourself starring dumbfounded at the screen, trying to dissect your own logic, and questioning the compiler for successfully building spaghetti code. Many programmers have experienced this. Myself included.
As we continue to develop our open source file utility libraries, we’ve shifted focus from continuous integration to understand the benefits and importance of creating supportive documentation. I believe that being able to effectively explain your program is a great skill in the open source community. We often make assumptions and “forget” to comment our code. If you know the language that means you shouldn’t have a problem figuring out what it does. Often this isn’t the case.
Do people actually readme?
Yes. The reality is, documents such as README and CONTRIBUTING are some of the most important files in your project. It’s the first screen users navigate to for insight. Having an effective README is a great way to spark a person’s interest in your project. They understand why this project matters, and how their contributions can benefit its growth.
“Bug free software that nobody knows how to use is just as bad as software that cannot be used because it’s so full of bugs.” Elliot Land
To create a great README, it’s important to understand it’s purpose. The goal is to enable new users quickly and easily set up by providing, the purpose of the project, setup and installation instructions, define APIs, give clear examples.
TIPS
Some tips to consider while writing your README:
- Use Markdown for styling and organizing your document
- Examine README’s from other projects for ideas and examples
- Document new features as their added
- This will not only help other developers better understand the changes but also save time retracing those changes
- It will also give you a different perspective on the current state of the project
- Provide descriptive examples. Utilize images, GIFs, snippets etc.
- Clearly label steps and procedures
Template
Below is a README template I created for the fileside project.
This template can be used as a starting point for your project.