Well, we were there.
Documentation can play a huge role.
It can affect the developers when they need to return to a project that has been sitting on a shelf for years or onboard a new team member.
It can be a significant risk for the client when the product has to be handed over, and they start maintaining it themselves.
Without a proper set of minimum viable documentation, it can become more expensive than writing it in the first place.
Sadly, when it was the right time to start, priorities laid on different aspects of the development process.
Quite often it is the budget that sets the boundaries because the value is not always visible or arrives too late.
So how can we make it valuable for everybody without putting a big hole in our budget?Starting Steps: onboarding a team memberThere are many projects in our development vault.
Some of them well documented, some have a line or two written down in the README file, and some have information laying around in all sorts of communication channels.
Writing documentation seemed to be like fighting a monster.
Some took up the challenge only to find that it was not that scary.
Others decided to let somebody else deal with it.
We wanted to make it less intimidating and turn it into a natural part of the process.
For that, we had to start from the beginning.
We first saw places for improvements when we had to onboard a new developer to the team.
Our challenge was to find a way to communicate the development process as efficiently as possible and provide a source for the new person to come back to.
We created a template for the team members to fill which listed all development related information and workflow of the team.
This template helped the initial developers not to miss any vital information and gave the new team member a place to come back to when they needed it.
Fortunately, a perfect situation occurred.
Two projects exchanged developers.
This gave us an excellent testing field for the template to validate the solution.
The developers filled the document and carried out the onboarding process for each other.
Instantly we could get feedback and revise the template.
With a little effort and luck on our side, we already had a solid starting ground.
Okay, but this only solves one problem — having documentation for onboarding.
We were still lacking documentation for smaller scale projects and a habit of creating it.
Moving forwardWe had done our fair share of only-ifs and what-if’s, got burned from past mistakes and licked our wounds.
Now it was time to take action so we could improve.
For larger systems and projects we have enough documentation.
This is part of our process that starts with drafting architecture and analyzing requirements.
For smaller scale projects, these phases are shorter and therefore do not always produce enough documentation.
From the onboarding template, we found a way to generate a starting point for the project’s ReadMe.
There are many examples of ReadMe-s available, but we needed something that was custom made for our company’s processes.
We started with defining the roles in the development phases.
Mapping down all the parties helps to identify common information needed.
Once we had them mapped, we also took a more in-depth look into what those parties are interested in.
For example, there is no need for the designer to know all the technical constraints, but they are interested in where to find the application and whom to contact when they have questions.
As we aimed to keep the information sufficient, but minimal, we filtered out the most critical aspects of those shared values.
We also needed to find a way to make it easily accessible and updatable.
Without having a proper habit of writing documentation or keeping it up to date, it is hard to motivate oneself.
We found it most comfortable to include it as part of a development task.
Including documentation as part of the definition of done seemed the most effortless.
It helps to create a habit and make it a natural part of a task’s lifecycle.
It helps to keep the documentation process agile.
With little effort, we have a way to keep the information up to date and relevant without producing waste.
After several sessions, we finally had a template to include into our projects that were structured and is not some scary Documentation Monster to fill giving us a stepping stone to improve even more and see the importance of documentation well before when it is actually needed.
Key takeawaysLike in the agile world, we are still moving with the currents and improving the process, but we are in a lot better place than a while ago.
Without dismissing the principles of agile methodology, we got to a documentation process that is lean and effective.
It keeps its value by being updated when there’s a need for it.
What we learned:Start writing handover documentation as early as possibleWhen dealing with a small project, keep the documentation efficient and let it grow with the project.
Keep writing documentation as part of issue’s definition of done rather than a separate task.
This way you will have an agile documentation processDeveloping templates for certain types of documentation will make the process seem less scary.
Let us know in the comments section which documentation monsters have you faced and how did you tackle them?Mobi Lab is a product design and development company.
We run our product development in-house but also work in joint teams with clients in Europe and US.
Mobi Lab is one of the fifty Google Certified Agencies for Android technology.
.. More details