Documenting in the Age of Microservices

Yes, I know, I'm documenting documentation.  I wanted to take some time and outline how I believe we can accomplish a scalable and reusable platform through documentation, and why it's important.

Why Should I Document?

There's probably not any immediate value in documentation, right? We all know how our own code base works, except the 1 new guy, and we can spin him up no problem.  There might be another team that needs our services in the future, but we can deal with that when it happens.  And... it. takes. forever.

Writing can be hard, and writing technical docs can be harder.  We're not particularly prone to the Eglinish(typo intended) language (or other languages) to begin with.. we're coders.

But documentation is important, and here's why I think that:

• You might not always be around to "train that other team".
• By the time the other team wants to start using our services, it's too late.  If we start documenting then, they have to wait even longer to begin using our products.
• We forget things pretty quickly
• We get a lot of questions that if we had written down the answers to begin with we wouldn't be getting, and it probably takes a similar amount of time to write the answers down as it takes to explain to someone else.
  • AND, if more than 1 person asks you for the same information, you're now taking more time than it would have taken to write it down

I'm especially guilty at point #4.  I get asked questions all the time, such as "How do I query for customer data?".  And only yesterday did I actually document any of it.

Types of Documentation

Between lots of online reading, and a coworker's lunch session, I have broken down documentation into four (4) categories, and assigned responsibilities to each one.  The where of it may change, but the gist remains.

1. Technical documentation
2. Edge documentation
3. Architectural documentation
4. Operations documentation

Across all of these, I follow one golden rule: Documentation should be as close to the code as possible, while remaining valuable.

Why Close to Code?

Most of us are writing and maintaining code.  There are two core reasons from my perspective:

1. You're in the code anyway, so it's easy to make sure to notice, and update the documentation you need as you make changes
2. When other people go looking for how to use something, they'll likely go to the code or the service, so they'll be able to immediately find how to use it

As I said above, writing documentation is hard, remembering to do it is harder, so the closer it is to your normal workflow, the easier it is to update.

Technical Documentation

Question: What do I need to know as a developer who wants to work on the service.

They answer questions like:

1. What are the responsibilities of this service?
2. How do I run it? (How do I setup my machine to run it?)
3. How do I contribute?
4. How do I debug?
5. How do I go about testing my changes, and validating the application?
6. How do I go about getting my changes merged in?
7. How does code work, and why does it work a given way?
8. Who do I contact if I have more questions?

Location: A lot of this information is the code.  These should be in the readme, code comments, and github wikis. There are great templates online for how to do this, like this one.

Edge Documentation

Question: How do I consume the service or library? What is the underlying logic of the calls?

Edge documentation is what appears around the "edges" of any given service or library.  This documentation is how someone interacts with it, and usually doesn't contain much, if anything, about how it works under-the-hood. While that stuff can be important, it's usually just bloat for documentation like this, and gets in the way of the reader accomplishing what they want to do.

Example questions:

1. What does this service do?
2. If I want to use this service, how do I do that?
3. Examples of using the service
4. Explanation of business models for that service.  What are the high-level concepts?
5. What are the given actions or side-effects of any given call?  What is the business logic, and how do I consume it?
6. Who do I contact if I have more questions?

Location: For us, Swagger made a lot of sense, since we write mostly web services.  We should continue to maintain documentation as-close-to-code as possible.  This is easy to maintain, while still making it available externally so someone only needs to know the URL of the service and not find it in github.  We should also link from other resources (eg a wiki).

For libraries, maybe something like Doxygen makes more sense for you, or a good old fashioned wiki.

Architectural Documentation

Question: How does this service interact with other services? How does it fit into the bigger picture?

Not all people have to deal with this level of documentation. It's only critical when you're developing larger systems and a given application is just a piece of the puzzle.

However, if you do need it, don't leave this part out. Someday it might not be obvious how things work together. This is where all the diagrams go.  This explains how piece(s) of the puzzle fit together, what talks to who, and why the flow of data is the way it is.

Location: Probably a wiki, or wherever your company keeps centralized documentation.

Operations Documentation

Question: Something is going wrong, or is suspected of going wrong; how do I triage and find information related to this service?

This is information for someone who needs to figure out something, potentially quickly, about why something is going wrong.

• How does the service work?
• Where is it deployed?
• How do I find metrics on the service?
• How do I do common actions to fix the service?
  • Restart it?
  • Check its health?

Location: Probably a wiki, or operations manual

Final

The moral of this story is: don't document when it's too late, and don't document only when it's immediately valuable. But also don't document immediately.. if the application is still in the prototype state, and you aren't even sure someone will use it, there's no reason to spend time writing docs.

But don't wait until it's too late.