This is my first post anywhere, so be gentle! :)
Also, this is my opinion based on my work experience and in the type of projects I have encountered. I would love to hear your opinions on the article in the comments!
I know what you're thinking. Everyone hates documenting stuff.
Take for example doing your taxes. I hated doing the taxes until they implemented a mechanism for me to click "Yes, I confirm" and be done with it. But we do taxes because we have to. Documenting is based on the same principle.
Nowadays I've turned a new leaf and I'm actually really fond of documenting. I try to document everything I can, with as much detail as necessary. I believe in teaching my junior team members the same thing. As soon as they enter my team they quickly realize if it's Not Documented, It's Not Done.
Note: Documenting and Commenting are two separate things. Think of code like a problem: while commenting mitigates, documenting fixes.
When I started my first job, the moment we got an email saying that we won a new contract, was also the moment we started writing the code. There is no worse practice than this in software development!
Software development is like building a house. First you study the best approach, you review it, then you get your hands dirty.
This has happened to me more times than I can remember. (Un)Fortunately I'm usually the firefighter who needs to put out some major fires in different types of projects. Maybe that's one of the reasons why I now like to document a lot.
Imagine you are put on a project already on course and you have 3 days to implement a feature without absolutely no context at all. What would you give to see a really good written manual about what the project does, and how does it do it.
Everyone likes starting a project from scratch and just going heads on to the code. Nobody likes entering a mid-finishing project without knowing properly what happened.
Help your local firefighter colleagues and document people! Be it in .md, a word file, or even a Visio that explains the flow of the application you're developing!
I hoped you enjoyed the article!
- What are your feelings on documenting? Do you like it or do you hate it?
- How do you usually document?
- Are you normally the firefighter in you team? :)