Who the documentation is for ?
The documentation are intended for you, your coworkers and the other users who might be using your code.
Why Documentation ?
It helps collaborating efficient and easy. Plus after some time down the road, you yourselves would have forgotten the line of thinking, for why you did code the way you did. Documentation helps you remember your line of thinking, not only to yourselves but others too.
Why README ?
- It helps anyone who first visits your project to get up to the speed, up and running.
Best Practices for README file in any projects ?
- README file should be all caps – to emphasise its importance and increase visibility
- Must have
- Title – often in bold and slightly biogger font size than normal
- Description – Not too long and neither too short. A sentence or two.
- Getting Started Guide
- Any info that is absolutely necessary for your project and that you will need to get up and running e.g
- Installation notes for any dependent libraries
- Usage : How to use / run
- Include Regular Updates , as your code base grows, such as :
- Known bugs : Very useful for users, or else users might be unnecessarily worrying about why the code is not working.
- Frequently Asked Questions : If you are asked the same question again and again
- Table of Contents : Great way to help user jump into section, as your README gets longer.
PS : Most important is to think in terms of some one who has never seen your code.
See a sample here at https://github.com/beekal/MachieneLearningProjects/tree/master/Supervised%20Learning/Loan%20Interest%20Rate%20Influencer%20Predictor
A Simple Sample README Template
# Project Title (: One Paragraph of project description goes here) #Description : (1-2 liner description of the project) ## Getting Started Guide : - Any info that is absolutely necessary for your project and that you will need to get up and running e.g - Installation notes for any dependent libraries ### Prerequisites Give examples ### Installing A step by step series of examples that tell you have to get a development env running - Give the example - And repeat until finished End with an example of getting some data out of the system or using it for a little demo ## Running the tests Explain how to run the automated tests for this system ## Usage : How to use / run instructions here ``` Run codes here ``` ## Known Bugs -If Present ## Frequently Asked Questions - If Present ## Table Of Contents (If README is too long)
Happy Documenting and Have a Good Day !! 🙂