After working for more than 5 years in the field of Development I started realizing the importance of Documentation, and hence I thought to write on documenting README.md file.
Here are some of the patterns I personally follow and made it a mandate to my team after creating a new repository or before committing codebase in existing repository, have a look at my README.md and markdown all informative notes.
Project title
These services are part of Blah Blah Blah Project.
Screens
Just to let you guys know, you can also add gifs in your (readme.md)markdown file.
Before you commit
Before committing code please ensure,
- README.md is updated
- A successful build and jar is deployed on nexus
- All newly implemented APIs are documented
- All newly added properties are documented in additional-spring-configuration-metadata.json
Libraries used
- Spring Boot 1.5.1.RELEASE
- Custom: Exceptions, File IO, Rest Authentication
- Spring Boot Test
- JSON Library(javax.json)
- Swagger API
- Hibernate Validation API (org.hibernate)
- Random Numbers and String Generators(smt-random-strings and smt-random-numbers)
Features
These services can perform,
- Employee CRUD operations.
Installing
A step by step series of examples that tell you how to get a development env running
Deployment
Add additional notes about how to deploy this on a live system
JIRA References
Add all JIRA Tickets with Hyperlinks
Versions
- 1.0-SNAPSHOT: Contains Add, View, Update, and Delete Employees
Developers
- Pratik Ambani(Pratik.ambani@companydomain.com)
License
A short snippet describing the license (MIT, Apache etc)
As usual, suggestions are always welcomed. Happy Coding and may the code bless you. 😇
TIP: Keep your README.md updated if you believe in KARMA. 😉
Top comments (5)
Hey Pratik,
I completely agree that documentation is on of the most importation thing during the development of software and every git-Repository should have a least a README file.
My steps usually are adding tags to a GitHub repository after I created a new repository and update the README during development. For many student projects, in which we also developed UIs, I often add screenshots after the project has ended. This gives interested people a little preview of what was built and how it looked like. Usually research projects are not very longer maintained, so often you will not be able to start an application after a couple of months again. So if it was hosted on a university server, it literally dies after the season 👋 A README with pictures gives also future employees a way to see what you have built and understand it more easily, also if they are not so tech related. For my side projects I do this every time and it is very nice to see your process over time.
For open-source projects and libraries I also want to mention that badges are also a good way to show stats and maintenance. I found some nice badges here: shields.io
If a README contains example code and/or output, it should be 'rebuilt' before committing. This guards against stale or broken examples.
The rebuild should:
GitHub Flavored Markdown does not support file inclusion, so I've put up a Ruby gem, markdown_helper, that does support it. File inclusion can be accomplished from the command-line or from within Ruby code.
See the documentation over at GitHub.
I am glad to see other understanding the importance of documentation. For addition examples of good Readme's checkout github.com/matiassingers/awesome-r... .
I love READMEs. It's like proof that you want people to use your stuff. The only time I don't add READMEs is when I want to save my work but don't other people to use it yet.
I believe that before you commit should be moved to CONTRIBUTE.md