There is no such thing as bad documentation

The notepad++ documentation page sums it up perfectly.

The last couple of assignments I've been on, documentation has transformed the quality of the work delivered by the team and it actually put the team in higher gear.

Documentation is viewed by many as the least interesting thing to do in their job. I was one of those people when I started my life as a professional programmer in 2006. Hack, even during my study I didn't like it. I still don't consider writing documentation as the nicest thing to do. However, I did found out that documentation, yes any documentation, has the biggest impact on team success.

In this blogpost I want to share some thoughts on documentation, which can be applied to any type of team.

Bad documentation is better then no documentation

Documentation comes mostly at the end of any change, incident, implementation or even design. We all know that any project or initiative takes more time then we originally thought because we are very bad at estimating work. When this happens, the easiest thing to drop is documentation. The idea is that we can always do it later and there is no business value added by writing documentation. WRONG! There will be no "later" and the business is hurt when problems take way more time to fix.  

Some people don't want to start writing documentation because they think they are bad at writing good documentation. Probably they are right but we don't need good documentation to improve the team and product. We need to have documentation. If you think you are so bad at writing, start creating screenshots and add minimal text. Even that is better then no documentation.

Keep writing, it will get easier and better

I still remember when I first realised the importance of documentation. I was doing a consultancy project in a time when I also blogged a lot more, sorry ;-), and my documentation was read by multiple engineers and managers and everyone found it useful and instead of emailing me with questions they started looking at the documentation and only contacted me when they missed something.

At that time I was writing (blogging/documentation/etc.) for more then 8 years and I noticed that is became easier and easier to write better documentation.

So yes, you do need to invest time before you're writing skills will improve but that day will definitely come. The great thing is that when your writing improves it also gets easier and takes you less time. It's a continous cycle.

Your colleagues will be grateful and will improve their work as well

Documentation also creates an improvent cycle within a team. Once you are writing documentation and the team is using your documentation they will appreciate it and will start to write as well. This will improve their skills and their confidence that they are able to write documentation. Rinse, repeat.

I am currently reading and investigating the concept of High Performing Teams. I really believe that documentation is a key thing to have when you want to become a High Performing Team. It makes your work easier, quicker and also more fun to do. This will impact team chemistry as well because collaborating on documentation will improve the situation even more.

New team members will be up and running much faster

When new members join a team, one of the first things they do is look for documentation to get to know the environment. If that is not available they will be paired with a colleague who needs to explain everything. This will repeat itself every time a new member joins the team.

If you have documentation available it will decrease the burden on the colleagues. But also it will allow the new joiner to go over the documentation and start to look around and figure stuff out. It's just very friendly and a good onboarding experience for new joiners.

Tip, allow the new team member to fix any documentation in his or her first weeks. It's always good to have a pair of fresh eyes looking at the documentation that is already there and it will improve the situation for the next team member.

Handover from members leaving the team should not be needed

Once a team member decides to leave the team he or she get's asked to write everything down that he or she was working on so someone else can take over. This should not be needed. In my opinion it even almost always fails. The team member is already somewhere else with their thoughts. The quality will suffer.

If you make writing an integral part of your work, handover documentation is not needed and the team member can focus on finishing the things they were working on. This to make sure the cut-off is as easy as possible for everyone.

Tools make life easier and for once are a game changer

A lot of people start with getting the perfect tool in place before they start doing anything and most of the time this will not change the game. For documentation however I've noticed that it does change the game.

We are coming from a world, most organizations are even still there, where enterprise organisations are relying on SharePoint for documentation. Documents are written and stored in Word-format. This creates a barrier to start because people will want to create a structure before they start writing. Also it limits the search capabilities across multiple documents.

In my experience webbased wiki's are the perfect starting point for good documentation. They make it easy to start and collaborate on documentation. Search is also a no brainer.

For me Atlassian Confluence is a clear winner with it's easy to use UI and great add-ins to add diagrams, table of content, code blocks, etc.

To summarize

To sum things up:

• Select an easy to use webbased documentation solution
• Start writing / dumping text on the solution
• Improve documentation and structure along the go
• Enjoy a higher performing team and a better service to the customer -> BUSINESS VALUE