Creating a documentation culture in the Android team

In this article, we will examine the importance of creating comprehensive documentation for a project, and what we have done here in the Android team at Babylon Health over the last few years to get us to where we are now: We have reasonably well-maintained documentation on all essential topics that touch on every aspect of the project, from probation objectives for new starters to our architecture, to how to organise a hackathon! It was a bumpy ride, and some of the things we tried didn’t work that well, but we learned from our mistakes and iterated over the initial solutions until we found something that worked for the team.

Hopefully, everyone will agree that documentation is important for an engineering project, for several reasons:

• Onboarding is easier. New starters have material to go through with less hand-holding to get up to speed, from a technical as well as process perspective. See Joao Alves’s article for more details on creating a great onboarding experience!
• People in different timezones find it challenging to operate in a project with nothing documented, especially as other engineers are not available for part of their day. Here at Babylon Health, about 20% of the team is working remotely from Europe, while another 10% of the team is in the US.
• Documentation is a reference point when people forget the details of a process or convention. No one is expected to remember everything, and information/processes should not just live in people’s minds (and go away when they forget it or move to another job).
• Documentation helps with consistency both in code, but also overall in operations. For example, any process that involves manual steps (assuming that they can’t be automated) should include documentation about the exact steps that need to be performed. The less thinking someone has to do to decide exactly what the steps are, the less error-prone the process is.

So, about 3 years ago when we started building the Android team here at Babylon Health we decided to create some documentation for the project, but before even starting, we made some quick decisions without really thinking about it:

• We decided to document everything in Confluence. At the time this felt like the only way, although fast forward a few years it was clear that the documentation was sitting too far away from the tool that the engineers spent most of their day in, Android Studio.
• We agreed that everyone owns the documentation. It quickly became clear that “everyone” means “no one”. 😅
• We agreed to have everyone add in topics that were missing in an ad-hoc fashion. This meant that many topics were missing from the docs, others had unneeded details.
• We didn’t discuss particular styling conventions for the documentation. While this seems like a small thing, the lack of a certain degree of consistency made the docs harder to read and navigate.
• We didn’t discuss a process to update the docs. That meant that within a year most of the documentation pages were quite out of date.

We stayed with the documentation on Confluence for about 2 years. Up to that point, the engineering team had grown rather slowly, and even though everyone acknowledged the problem, there was no big driving force to push us to revisit the situation.

Enter Blitzscaling

In 2018 we went through a period of Blitzscaling during which we tripled the size of the team. We also hired remote engineers across Europe, and the U.S. At the first stages of this period, it became very clear that we needed to rethink our documentation strategy. We sat with the team and decided the following:

• The documentation would sit in the repository, next to the code as markdown files.
• Every page of the documentation is assigned to someone. Anyone is welcome to change it, but the assignee is responsible for making sure it is kept up to date.

This is what the footer of every page looks like. A person assigned to it, with a link that can be clicked to start a discussion on slack!

• We created a list of topics that we felt should be tackled first. After those core topics were documented, we could move to other topics. It’s worth noting that some of these topics already existed in Confluence (albeit rather out of date) and needed to be updated, converted to markdown and then moved to the repository.
• On how much detail to go into, we chose to be pragmatic. The driving force was that too little documentation might raise questions on a topic, while too much might overwhelm people and is also harder to maintain. As such, for topics that aren’t that important, we went for a tiny bit of documentation, for example simply pointing to the existence of some tools. At the same time, for other topics like our architecture, we went into a lot more detail, providing comprehensive examples of how one can use it to build a new screen in the application.
• We agreed on a style spec for markdown files, and we wrote a lint tool for markdown files. This tool also validates all local links in the docs to make sure that the file they link to exists! This allowed us to heavily interconnect the documentation pages with one another, having a guarantee that if a file is renamed and the link stops working, the Pull Request that made the change is going to fail! It also allowed us to do the same for linking source code files from the docs.
• We defined a process to update the docs; a 1h 30m “documentation hackathon” meeting once per month, where we sit with the whole Android team and silently write documentation. This worked like a charm!
• We created a new CI workflow so that documentation only Pull Requests do not run all checks (tests, static analysis tools, building the apps, etc.) but only execute the markdown lint tool mentioned above.
• We created a CI job running a couple of times per month to notify the whole team of all documentation PRs that were recently merged (PRs are identified via the branch name which always starts with documentation/).

With this process, in 6 months we had about 80% of the initial 80 or so topics written up, and fast forward another 6 months we have all of the initial topics plus many more on top of that, covering in total about 140 different topics. The main categories that we have are:

• Android Studio plugin: we have a custom plugin that generates code for our architecture, plus a few more things. See this talk for more.
• Architecture: contains everything around our MVI and SDK architecture.
• CI: contains everything around our Jenkins CI system.
• How to: contains things like how to create a new screen in the app, how to create a new SDK or a new application flavor, etc.
• Lead: contains things relevant to the engineering managers of the team like approving contractor invoices, managing support rotations, probation reviews, etc.
• Onboarding: contains anything that a new starter might need in their first few weeks, like how to set up their computer, what tasks they should start doing in their first couple of weeks, what their probation objectives are, what the team roles and values, what the team structure is, etc.
• Process: anything from how to add a new permission in the mobile apps, what is our process around code owners, how to upgrade a library, what the release process looks like, etc.
• Project conventions: contains things like styling themes, Java conventions, Kotlin conventions, etc.
• Recruitment: contains any part of our recruitment process that is not already open-source — for example our tech-test grading guidelines.
• SDKs: contains information about our SDKs like how one can build them and publish them, the sample app, the release notes document that accompanies them, etc.
• Security: contains all security practices that we are following in the team.
• Testing: contains all testing conventions (it was too big of a category to go into the Project conventions category!).
• Tooling: contains things like how to use our static analysis tools, dagger reflect, Gradle enterprise, mainframer, etc.
• Other: well, anything else really. We have things like the policy for attending conferences, links to product specs (that are managed by the cross-functional teams and live in Confluence), ideas about future articles that the team is planning to write, etc.

Documenting technical proposals

For a few months, we experimented with documenting technical project proposals in the same format as our documentation, discussing them via Pull Requests and then adding them into the codebase next to the docs, but ended up using a collaboration tool called Threads as it provided many benefits over this approach for engaging with the team. Details will be covered in a separate article.

The future

With all these in mind, we have a couple of things planned for the future still:

• Hosting the documentation internally: We are experimenting with hosting the docs with Ktor so that every new engineer can easily access them even before they get access to GitHub (which usually happens at the end of their first day in Babylon).
• Hosting the documentation externally: We are thinking about selecting a part of the documentation and open-sourcing it. This is so that we can be transparent with the community on how we operate and help out other companies that are now building their processes.

At Babylon we believe it’s possible to put an accessible and affordable health service in the hands of every person on earth. The technology we use is at the heart and soul of that mission. Babylon is a Healthcare Platform, currently providing online consultations via in-app video and phone calls, AI-assisted Triage and Predictive Health Assistance.

If you are interested in helping us build the future of healthcare, please find our open roles here.

Follow us on Twitter @Babylon_Eng