What is your default documentation process?

github logo ・1 min read

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?

twitter logo DISCUSS (4)
markdown guide

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.


I always want a README with instructions to get from git clone to 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.md file 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.


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)

Classic DEV Post from Jul 17

What are you (still) not interested in learning?

I'm interested in hearing not only what you are *not* interested in learning. But if you answered the question last time, has anything changed?

Scott Harrison profile image