How to write a Good Readme
Writing a Good Readme
Introduction:
Writing a good readme is essential for any project. While generating it automatically is easy, the challenge lies in creating a well-written and informative readme. In this post, we'll discuss some helpful resources and questions to guide you in writing a quality readme.
Helpful Resources:
Questions to Ask Yourself:
To write a quality readme, consider the following questions:
- Who Did the Project:
- What is it?
- When Did You Work on It?
- Where Have You Been?
- What Does it Look Like?
- Progression and Future Plans:
- What's in it?
- Installation Instructions:
- Project Origin:
If you worked on the project alone, it's you. However, if it was a group effort, acknowledge your teammates by mentioning their names/pseudonyms and linking to their GitHub profiles.
Clearly explain what the project is about. Is it a mobile application for finding soul mates among English-speaking rhubarb lovers? Be precise and concise.
Specify when you started and completed the project. While the GitHub repository displays dates, it's helpful to have a human explanation. For example, mention that the website showcasing grey shrimp lovers was created during the summer of 2015 as part of a hackathon in Miribel. Highlight any important changes made over time.
Describe your career path during the project's development. It adds context to your work. It's different to say you developed a billing system as a Senior Developer at BigPrestigious Box compared to being a learner at BeCodeQuiFormeDesNewbies. Share where you were in your career at the time.
Include a preview of your project, such as a screenshot or application logo. Providing a link to an online demo adds an extra touch and allows readers to experience your project firsthand.
Indicate whether the project is complete or still in progress. If you want to make changes or invite others to contribute, mention it here.
Summarize the key aspects of your project in a sentence. For instance, mention if it follows an MVC architecture or if it's built with Laravel. If there's a database, briefly describe its complexity or share the conceptual data model (MCD).
Provide clear instructions on how to set up the project locally. This helps others utilize or contribute to your work.
Specify whether the project was for a client or an exercise during a class. Adding context gives readers a better understanding of the project's background.
Conclusion:
In conclusion, remember that a picture is worth a thousand words. Include relevant screenshots or visual examples to enhance your readme and provide a comprehensive understanding of your project.
