Internal Developer Documentation

A very common problem I see in most companies I work with, is both a lack of internal developer documentation, and also a lack of appreciation for how important this really is. There seems to be this assumption that the developer who has all that undocumented knowledge in their head (yes, you know the person) will always be around. They'll never leave for another job, they'll never get run over by a bus, they will always be available. Okay, hopefully the bus thing will never happen, but you get the point! Even when the developer goes on holiday - their knowledge is not available until they get back.

The developer leaving or being on holiday isn't the only issue though. We've all heard about the massive cost that is associated with an interruption - especially for developers. At one company I worked for a few years ago - there was one developer who knew and had written pretty much most of the entire system. And he was constantly being interrupted and asked questions. Then when answering those questions - that knowledge would be passed on verbally to that one person who asked the question. So that interruption wasn't even sharing the information with the team - it was just sharing it with a single person.

What if that information was in an internal wiki instead so that anyone could read up and study additional parts of the code base? What if new starters were free to study and read about how the system works and historic decisions? Now obviously, you can look at and study the code - even bits of code you're not current working on. Infact, you should most certainly be doing this anyway! But not everything is document-able by code. Code should show a deeper implementation - but documentation should explain core concepts at a higher-level, reasons decisions were made, etc.

What kind of documentation are we talking about?

I should point out at this stage, that I'm not talking about product documentation to be released to customers or stakeholders. I'm talking about internal technical developer documentation in which devs can be free to add to and update existing documentation. It should be easy and effortless to do so, without friction that would come from updating publicly released product documentation.

I'm also not talking about API or DLL reference detailing API request/responses etc or method calls. These can be automatically generated with tools like Swagger and Doxygen. Don't manually type these out, that's just a waste of time. I'm talking about higher-level concepts and explanations of how the system fits together, architecture, and how the less-obvious features should work.

So why do so many companies fail at this?

Here are some common excuses I hear ...

• "We don't have enough time!"
• "No-one would read it anyway ¯\(ツ)/¯"
• "Documentation gets out of date"
• "The code itself should be self-documenting"

Let's take each of these one at at time ...

"We don't have enough time!"

If you don't have time now whilst the feature is fresh in your head - then why will you have time at a later date when you've forgotten the details, and someone comes over asking you about it? You'll have to find time then to dig through your code and remind yourself so you can pass on the knowledge, so why not save your future self all the extra time? And that's assuming you only get asked that thing once. Also, the dev that wrote the feature might not be available, so that's going to cost other devs even more time trying to figure stuff out, rather than just reading a high-level description in a wiki.

Also, be careful of falling into the trap of over-documenting. As I mentioned earlier, try to explain core concepts and things that are non-obvious - do not just repeat what the code is already telling you! This is a waste of time, and adds too much noise to the documentation, meaning it's less likely that people will read it, or be able to find what they're looking for.

We'll happily throw a few paragraphs into an email explaining something - so why not spend that time instead to put it into the wiki instead, and then just email a link? It doesn't have to take that long at all, and will save the team time in the long run.

"No-one would read it anyway ¯\(ツ)/¯"

This is true IF documentation and the wiki isn't a core part of the company culture. If it's expected that all devs keep the wiki up-to-date as they add features and make changes, then the wiki becomes an integral part of the team. It may sound silly, but even how polished the UI for the wiki looks can make a big difference. If you're working in an ugly wiki with a really nasty WYSIWYG editor - then team motivation to contribute is likely to drop fast!

Another reason why people might ignore documentation is if they can't easily find what they're looking for. This is why it's important to keep the internal documentation all in one place rather than lots of different places - wiki, Sharepoint, Word docs, Markdown files in Git, etc. Have a single wiki, and embrace that single place to go for internal documentation.

"Documentation gets out of date"

This is why it's important that there's little resistance to contributing, and everyone feels invested in the wiki. If someone sees that something is wrong or out of date - then it should be effortless to update it. And everyone needs to know that they should be updating things that are incorrect as soon as they spot it.

"The code itself should be self-documenting"

The codebase certainly forms a kind of documentation - showing the detail of how things work. It doesn't explain a lot of core concepts though - or the whys and reasons things were done in a certain way. And also the reasons they specifically weren't done in a certain way.

Summary

There are many different wiki solutions out there to choose from. Here are just a few ...

• Confluence
• Github Wikis
• Notion
• VSTS Wikis

I'm certainly not going to tell you which solution you should be using - but as mentioned earlier, it's surprising how important it is that it looks good and has great UX when motivating your team to embrace both reading and writing internal developer documentation. Getting your team to embrace documentation isn't going to be easy - as the average developer doesn't actually enjoy it. But picking an ugly old-fashioned wiki that is a pain to use is very unlikely to motivate the team enough for it to become a habit and a part of the team culture.

Also, make sure that this is a part of your feature release cycle. Plan, develop, test, DOCUMENT. Your feature isn't 'done' until either it's documented in the wiki as a high-level overview of how it works and reasons decisions were made - or at least you've consciously made a decision that documentation isn't required and can honestly give a genuine reason for this.

I know you may find documentation boring, but it really is a major weak point of many companies I see, causing lots of longer term issues with reliance on knowledge in developers' heads. Documentation can actually be quite enjoyable when you're not over-documenting or trying to write API references. Treat it as writing a blog post. Try to add value to what you write, and ask yourself how what you're writing might help future-you or your colleagues.

Please retweet if you enjoyed this post ...

Blogged: "Internal Developer Documentation" https://t.co/xo1olvHEZS #documentation #softwaredevelopment pic.twitter.com/KEQCZWttEV

— Dan Clarke (@dracan) April 7, 2018