My core pet peeve of the last 10 years is the lack of documentation I’ve encountered with Software Projects. Sometimes it’s as the consultant that’s called in after someone already charged a lot of money for a substandard job. Sometimes it’s that legacy project that sticks around through generations of developers who leave a company. Sometimes it’s the “we don’t have time” factor.

Documentation is a value-added part of any software project for a variety of reasons:

• Reference: The ability of software engineers involved with a project to look back and see why things were done the way they were, and to allow for knowing the limitations and potential of a project.
• On-boarding: Bringing new software engineers up to speed quickly without having to bounce around the company finding answers.
• New Projects: Proper documentation of old projects, including estimates and other data, is of great use for estimating similar projects. (Project Management and Business Analysis)
• Complicated code reviews are simplified.
• If someone gets hit by a bus, someone else can take over. Quickly.
• Legal: If a project is supposed to meet certain requirements, those requirements should be traced to the actual implementation.
• Teams: Proper documentation in an Agile or DevOps process allows team members to see what others are doing in similar areas of code, and allows easy identification of problem areas quickly.

These are just some of the reasons documentation is important. More often than not, I’ve ended up writing documentation at different companies because it simply did not exist before.

Why didn’t it exist? Here are the standard excuses:

• No Time: We didn’t have any time to write the documentation because we’re busy working on the next thing!
• “Me no write so good”: Fair enough, but there’s only one way to get better at writing.
• “It’s not my job, man”: Erm – no. Documentation is a part of software engineering. A big part.
• We don’t know how to organize it: Fair enough. Spend some time and figure it out and implement it.

At the base of all the excuses are 2 things that are really simple:

1. Software Developers generally don’t like writing documentation.
2. Management fails to have developers write documentation.

These 2 things are understandable, wrong, and amazingly easy to deal with if a company wants to.