Documentation is the least heralded aspect of creating software. I’ve found few people willing to write software documentation and fewer still who enjoy it. I understand why. Engineers want to write software, not write ABOUT software. Less still are those who want to write about the technology stack, tools, and programs that enable software to be written.
Time spent up front in writing documentation saves time in the end. How often has a new hire required extensive hand holding in getting their work stations set up with the correct versions of languages, frameworks, and applications? How many different people possess key pieces of information about the technology stack? Does someone new have to talk to all those people to get up and running? Shouldn’t all the necessary info be collected in one place?
As a dev who’s struggled through on-boarding processes I understand the importance of clear, easy to use documentation. In fact, what I’ve learned is that documentation should remove all the logical jumps often necessary to string concepts together. Good documentation doesn’t make you think – it does the opposite – it saves you from thinking so that you can use your noodle for actually solving problems.
Good documentation explains steps clearly, concepts simply, and uses examples to demonstrate syntax or commands. What’s pertinent is gathered in one place. And instructions are laid out sequentially and organized logically. There’s no researching who knows what and in what order this should be installed before that.
The sooner you get someone solving product defects the more profitable you are. Too often I’ve spent too much time solving on-boarding documentation defects instead. And in the process, tying up other devs, slowing the whole team.