Published on August 3, 2020
Documentation is hard and feels unrewarding. Therefore, it’s the last thing you write. When you start your project, you have a high level of motivation and this is how your development cycle looks like:
After a few months, your motivation starts to decrease and your development cycle looks like this:
Time passes. Your development cycle now looks like this:
Documentation is hard to write and hard to maintain. Even more at the end of the feature cycle, when you’ve forgotten all the edge cases you wrote.
It’s sad, because there are actually many benefits of having a great documentation, especially with side projects:
A complete, well-written documentation is always the sign of a great product. It’s easily the most powerful tool you have at your disposal if you know nothing about marketing and still want to gain some traction. READMEs are also a very powerful marketing tool that I should write about in the future.
I suggest to completely change how you write softwares.
Start with the documentation. That means: do not write a single line of code without having completely documented the feature you are about to write.
Then, write the code that supports this documentation, and write tests that match this code. Or write tests then the code if you are fan of TDD — it doesn’t really matter.
Sometimes, tests will show you that you missed something in your documentation. Update it accordingly.
Then push both the code and the documentation to production.
Later on, if you need to modify the feature, start by updating your documentation. Then update your code. Always start with the documentation.
Ideally, you would have a rule in your CI that prevent you from committing a feature without the associated documentation. I don't know how to do it programmatically, but you can simply have a checklist in your pull request template that lets you achieve this goal.
I don't like methodologies in general. Don’t waste time with TDD, BDD and other methodologies that seem to be designed to slow down side projects.
What’s really important is a software
Point 1 is covered by having tests. Write tests, always, but not too many.
Point 2 comes with experience. Making a software fast is a result of a lot of decisions and should be one of your priority, but you will only know how to it well after a few years of struggling with bad code.
Point 3 comes by forcing you to write documentation before you do anything.
Nothing else matters, really.
Hi from Canada 🇨🇦