Documenting every tiny detail is a little overkill

Documentation comes in many forms and different sizes. While I personally do think that documenting every tiny detail is a little overkill, there are small things that can done in the process of development that would act as a breadcrumb trail for others to follow! 🍞

1. Maintain Design Documents

Design documents detail the product requirements for a feature, and the technical implementation for the requirements. A design document gives other contributors a clear understanding of the impact points of this feature on the code base.

With each feature that is being developed, a new design document should be made. Anyone going through the design documents can see how the code base has evolved over time and what cause what change!

2. Detailing tasks

Whether it’s for a new feature or for fixing a bug, it’s always good to have a detailed task in your project management tool (JIRA, GitHub Projects, Trello etc.).

A good format for creating an task

Link the design document in all tasks that will be implementing the feature detailed in that document.

3. Detailing Pull Requests

While the above point was the pre-development phase, this is for the post-development phase.

Pull Requests are the final stage of development. It’s here that you have to be as detailed as possible.

A good format for creating an Pull Request

Try to always link the task(s) that a pull request is addressing in the description.

4. Maintain Guides

If your organisation maintains a code- or a design-style, maintain a guide that others can refer to.

You can also maintain guides for on-boarding, repetitive tasks (like build/deploy steps), etc.

While this might seem like some effort, just know that some day, someone is going to find your well structured PR, task or doc, or even the guide you’d written and think to themselves — “Damn. Whoever you are, I will find you and I will buy you a beer” 🍻