Developers: Documentation is Your Friend

August 3, 2014

Most developers that I’ve worked with over the years will either cringe or scoff at writing their own documentation. The most that you’ll get from a select few will be a few lines of comments within their code that they’ll refer to as documentation.

If you’re planning on making a move or not to the business side, though, I HIGHLY recommend that you at least take a few minutes out of every day to document what you’ve done. At the least, it helps you not be the only SME (Subject Matter Expert) and at the most, it prepares you for working on the product side.

I hear the groans and the cries from most tech folks of “But My PM/Product/Biz side person doesn’t document anything!”… and I can say right back to you that may be why you end up getting on an on-call rotation that won’t stop, or why you launched a product that no one seems to actually want or know how to use. Writing documentation, while derided as useless regardless of what side of the wall you land on, is integral as a skill-set.

I tend to use the Hit-By-The-Bus-Tomorrow analogy. If I was hit by a bus tomorrow, what would I have left over at work for someone to follow behind me and pick up my work from when I last looked at it? That’s pretty important as a developer, but most good devs can breadcrumb their way through the code and figure out what I was trying to work out.

What happens when it’s something I’ve left that’s just a bit less tangible than code? Say, where you wan the product to be for Phase One launch, heading into the other phases? Where’s that Product Roadmap? Where are the business requirements, or god forbid, the functional requirements? Documentation is your friend, Constant Reader, as sometimes it’s the only way that you can show that you did something at the end of the day. That lack of having something to show at the end of the day is the subject of another post, of course, but if you’re the kind of person that having something to check off your list is important to you, documentation is an easy win for that check-mark.

If you’re brand-new to writing documentation, you’re either going to over-complicate it, or keep it so brief that no one will understand it. It happens – like novel-writing, you’re allowed to have your first draft suck. I’ve never seen anyone come right out of the gate writing documentation that actually makes sense to someone else. So grab someone who’s either working on the same project to look over your first draft, or someone who’s more familiar with the product if you’re on your own.

Not even sure where to begin? There are lots of templates out there, including the standard Microsoft Office suite, and then there’s my favorite product suite, Atlassian. Their Confluence documentation suite has been an absolute godsend for my day-to-day work, and if your company uses their other projects, you can hook your ticketing system into your documentation with no real effort.

Whatever tools you go with using, don’t let the idea of writing documentation scare you off – it isn’t any harder than writing that code, or coming up with that update to the product you’re the owner of.

Leave a Reply

Your email address will not be published. Required fields are marked *

More Articles