Documentation driven development

This post describes how the mobile team at Blacklane works with documentation. We don’t claim that writing a documentation makes everyone’s work better however the documentation we write and maintain definitely makes our own work better and easier. When you do something long enough, you can see how your practice evolves along with your progress. As of the time of this writing we know what is it like when:

• your app has close to 100% documentation coverage
• when every team member understands the value of documentation and has good technical writing skills
• when in almost every case it is enough to find an answer to a question outside of your direct expertise without asking other team members.

We got there as a team and now we want to share our practice and insights to the developer community.

When you read code, start with documentation

There is very interesting topic on StackExchange Programmers: How do you dive into large code bases?. In that topic the summary of all answers to the subject question can be boiled down to the points:

1. Read all possible documentation about the code you’re starting to explore.
2. If documentation is missing or is not enough contact developers who know the code.
3. If there is no developer who knows the code, go a hard way of understanding it yourself using a debugger and other techniques like described in “Working Effectively with Legacy Code” by Michael Feathers. Make notes as you explore.

I read this as that documentation is always recommended as starting point for exploration. This can be a documentation for a code base a developer has to dive in at new job, documentation for a project a developer is suddenly switched to, documentation for a big open source project. In all of these cases having at least a high level overview of what is going on in code or in a problem domain is nice, or sometimes must, to have.

When you write code, start with documentation

It took a while for us to realize that documentation can be integrated into a developer workflow in the same way as Test-Driven Development is integrated: we call this “documentation first development” or jokingly “documentation-driven test-driven development”.

Before writing new or modifying existing code we review and adjust documentation. We try to make a source code correspond to business requirements as much as possible so that they can be traced directly to the source code and we do the same for documentation: we document requirements, green and red cases, gotchas, hacks, test cases etc. “Documentation first” clamps our workflow: documentation is constantly read and updated along with writing new or modification of existing code.

Documentation ecosystem is a team effort

One of the most common arguments against writing a documentation is that documentation easily becomes outdated and irrelevant.

Based on my limited experience of working in different teams and on different projects with or without, I think that to create healthy documentation ecosystem where the whole team is involved it should be more than 50% of proactive team members who are willing to write and maintain documentation i.e. it should be the majority.

Given a documentation is not a single developer effort, it is quite easy to fix irrelevant documentation you work with: as long as you see the documentation is outdated, you go and fix it and that’s it. If enough people contribute to documentation ecosystem, it is never outdated, the rest is a matter of luck of having such intelligent and responsible majority in a particular company, team, project etc.

Documentation tools

Our tool of choice for documentation is Confluence. We use it at its full power: we use its formatting primitives extensively, some examples are: Panel macro, code blocks, info and warning macros, graphs. We experiment with everything that makes documentation readable and pleasant to look at and work with and share with each other what we find.

At some point we also considered using in-source Github documentation or Github Wikis but decided to continue using Confluence as it was a company’s standard more accessible by our less technical colleagues.

Documentation examples

The following are only a few examples of types of documentation we have.

Feature-driven documentation

Each feature of mobile app is documented on a separate Confluence page. Most of the times feature is documented as a sequence:

• Requirements (general)
• Use cases (specific user actions and expected results)
• Test cases (complements use cases, more QA specific)
• Backend API notes
• Notes, gotchas, warnings (optional)
• Charts and diagrams (optional)

Mobile FAQ

Every time we asked or are asked a question and we don’t know an answer or catch ourselves answering it more than 2 times, we add question and answer to the FAQ. The question can be related to understanding the difference between how A-B bookings are handled versus hourly bookings or the details of a payment edge case.

QA documentation

Not only our QA documentation contains QA-specific docs about test devices, test data (fake credit cards, testing vouchers etc), testing tools but also our QA engineer directly contributes to documentation along with developers. It happens very often that based on feedback from QA rounds we clarify missing or confusing pieces in documentation.

Known issues

The following are two inter-related features that I think we are missing as they could additionally complement our existing documentation workflow.

Versioning

The only thing I am missing in Confluence is that documentation hosted along with source code would be more tightly integrated with a project’s lifecycle, especially its versions. It is not only about seeing revisions of a document, which Confluence provides, but rather about being able to revert to specific version of application to see the state of docs there. But since Github is not an option for non-developers, we don’t have an opportunity to experiment with this practice. Fortunately enough, so far we didn’t encounter any serious issues related to back compatibility in code or critical changes in business decisions so this problem is not critical at the moment.

Documentation of decision making process

This one, I think, is more important and relevant to our work: it is quite hard to come up with a document (or group of them) that would allow us to see and learn from history of development of our products and business in general. A knowledge about domain with long history can be very diversified and spread across different teams, departments, companies so it is hard to maintain complete integration of a whole process. So far we are proud of and confident in our evolving mobile documentation ecosystem however we are still missing this kind of better integration with the rest of domain knowledge other departments have. I believe this is very interesting problem that can only be solved with a team effort as it is hard to imagine a dedicated single man position for this kind of work.

Credits

Documentation ecosystem is our mobile team’s effort and I have never had a chance to work in a team with such a strong focus on business domain before joining Blacklane.

I would like to say a big thanks to my colleagues with whom we work on documentation that makes us more informed and thoughtful about our domain and helps us challenge the complexity of the problems we work on.

Conclusion

It is very often that documentation may seem redundant, however if you work in complex domains with a long history (even relatively simple domain with a long history can easily become complex) or deal with large codebases, well written documentation can be your only torch in darkness.

Documentation ecosystem is a team effort, not a single man’s — everyone should care about domain and contribute to an ecosystem. It is a pleasure to work in a team, where the knowledge is shared and trusted and helps you to solve business problems with a technical skills you have.

Let your project have a good documentation!