Often when we start a new project we will create a README.md with a brief outline of the project and steps to install. If the project is open source we may include a CONTRIBUTING.md. I feel like there is a lot of stuff that a README.md won't cover.
I'm interested in hearing what you have as your default setup for documentation when you start a new project?
Top comments (4)
README.md = what the software should do from a users point of view
doc/requirements.md = clarify and expand of the list all the user requirements. Move ones I wont do to section "Phase 2"
doc/design.md = how I am going to make the software. Notes here on environment details, tricky code bits, database schema.
tests/*.py = have a unit or integration test for each of the requirements
I like to keep everything in a text only format, and dont always to all the above but generally I'll stick to it. (even if it is a single line of text in one of the files)
I always want a README with instructions to get from
git cloneto that first successful boot of the project. This can include software and language requirements requirements, installation process, maybe a dummy env file as a prompt like.env.example. If I have to go to google just to start the project then something is wrong.After that it depends on the scope of the work I guess. At work we're documenting the README, requirements, database schema and other pertinent info in Confluence which is ok. It helps non-developers access this information.
The big win on my radar is encouraging everyone to JSDoc their functions (we use JS mostly) and set up auto generating docs. Adding unit tests for new work and gradually adding unit testing our core code would go a long way as well.
1 last thing is I often keep a
notes.mdfile or something that I can dump information in there for myself. I often git ignore this. It helps me keep track of ideas and features that I may not be working on right now but I want to come back to.For me, I like to have a README.md with technical details of what a project is setting out to do, how you can install it and what the requirements might be.
I also generally like to have a file that outlines who the project owners and contributors are (who the project manager is, who the designer is etc.) as well as explains the git flow we are using for this specific project.
I'm not super happy with this approach as I still feel like it isn't perfect.
Some process I like flowchar. Other ones I like process.st