Good documentation?

There are very few people who would deny importance and usefulness of the good documentation. Every person who has ever interacted with the somewhat complex system, be it software developer, QA, manager or a customer - is aware of how much time can a good documentation save (it can quite literally be a life saver). Or how much time and efforts can be wasted if the documentation is bad or even missing.

But what is the difference between good and bad documentation?

We believe that there are three fundamental traits which distinguish awesome documentation from the “meeeh” one.

Good documentation is:

• Complete (has an answer to your question)
• Up-to-date (has a correct answer to your question)
• Easily searchable/navigable (has a correct answer to your question in the expected place)

Those traits might sound obvious and simple but how many good software docs did you see lately?

And, to make things even more funny, there is one more challenge on the way to a good documentation. While everybody understands the importance of the documentation still there are very few people who likes writing it. And even less of those who actually CAN write it.

Those challenges are especially hard if we are talking about the custom-built software where the only documentation users are internal users and documentation is considered to be NOT a part of the product.

At Service360 we aim to solve all of those challenges in an easy and insightful way. We want to show how simple and fast can it be to write and maintain beautiful software documentation which provides tremendous value to the company with the very small investments.

Let us show how do we address all of the blockers on the way to a holy grail: useful software documentation.

Complete

From the years of development and maintenance of the software in the enterprise world we came to a conclusion that good service documentation should answer the following questions:

• What is this service doing?
• How to use the service?
• Who is the service owner?
• Where is this service deployed? How to deploy it?
• How to start developing/contributing?
• What technologies are used to build and run it?
• What kind of monitoring exists and how to react on alerts?
• What dependencies does the service have and on which apps do depend on it themselves?
• When was service released last time and what changes did this release bring?
• Who is an expert in this service/domain?
• Which emergency situations/outages did happen with the service and how they were mitigated?

If your documentation answers those questions there is a high change that it is a really good service documentation!

Unfortunately nowadays having just good service documentation is not enough. There is one more issue: enterprise world rarely has only one service/application. In the modern world of SOA/microservices landscapes it is not unusual to have 10s or 100s of services. Which are maintained by 10s or 100s of people. Which make multiple decisions a day while they build and maintain the software.

Here arises another side of the software documentation completeness: software architecture landscape is NOT only about software. It is also about people building and maintaining it, decisions made by those people, technologies used and a bit more.

We believe that in order to call your enterprise landscape documentation complete the documentation should answer also on questions like:

• How do services interact between each other?
• Which important cross service/domain technological decisions were made? Why? What alternatives were taken into account?
• What technologies are approved for usage and which are not? Why?
• Which teams do exist in the organisation and what are they responsible for?
• How every team member has contributed to an organisation?
• What skills does the team member possess?

So how does Service360 answer those questions? Well, not much magic involved: we’d like to introduce a few very simple standards for documentation.

Namely:

• Service Passport: a way to organise root README file of the repository so it will become structured and easily readable by both machine and humans
• Service Dependency Graph: simple text file in PlantUML format with minimal description of service dependencies
• DevOps Documentation Framework: folder structure with preset set of documentation types and a supporting process to keep it up-to-date
• Tech Radar Repository: a way to document and organise technological choices made inside of the organisation

All of those docs are stored in the code repositories under the version control (read more about it the Up-To-Date section(link)) and can be modified using you usual development flow.

Service360 is quite opinionated on what does good software landscape documentation means.

Up-to-date

There are multiple factors which contribute to an actuality (is there such a word?) of the documentation. If to simplify a bit we can say that in general documentation is up-to-date proportionally to:

• the amount of effort you spend on keeping it such
• the value it brings to the person maintaining it

Up-to-date = Value / Effort needed for maintenance

Documentation is up-to-date in the next cases:

• 100% up-to-date: documentation is autogenerated. [0 efforts]
• 90% up-to-date: documentation is used on daily basis or is a part of the main product [high value to the business]
• 80% up-to-date: documentation reside in the codebase repository and integrated into the development process (code review/DoD) [low efforts for keeping it up-to-date]
• 70% up-to-date: documentation is a part of your product support [high-to-mid value to the business]
• 60% up-to-date: there is a responsible person (tech writer) who tracks/writes the doc [mid value/mid efforts]
• …
• 20% up-to-date: “write-and-forget” standalone documentation solution which is rarely used (runbooks for theoretical cases) [low value]
• 10% up-to-date: “write-and-forget” standalone documentation solution (wiki/confluence) which is written for “someone, not me” [low value]

So, in order for the docs to stay actual we should aim to be “as green as possible”.

As you can see ideally all of the documentation should be auto-generated. But in case it can not be auto-generated (or requires non-proportional efforts to implement automation) it must at least reside in the codebase repository and be integrated into the usual development flow: be reviewed for being up-to-date during code review, for example.

This is the approach we took at Service360: all of the documentation is taken directly from the services' source code repository and a lot of it is autogenerated.

This also means that we do NOT have ANY WRITE interfaces here (remember all those confusing out-dated pages in your corporate wiki?). If documentation should be updated - it should be done via code repository (and go through your usual development process, which hopefully includes code/merge reviews).

Service360 is NOT one more wiki engine.

Easily searchable

You might have the most comprehensive and up-to-date documentation but if person in need can not find a piece of the puzzle in it - it is useless.

If the information you have is stored in the obscure place or you have documented EVERYTHING about the service and domain and amount of your documentation is bigger than Harry Potter saga (which is around 7 MB of text by the way) - you are in trouble (or have wasted a lot of efforts).

Service360 believes in simplicity. Documentation about service should be as minimal as possible (but not less than that!). So users would get the answers on the questions they have without reading through tons of the irrelevant info. We address this by introducing Service360 doc standards (link). Those docs are small and simple. It is easy to write and maintain them.

Service360 also provides neat and simple interface to access this data in the centralised fashion. So you would not need to guess where should you get info you are searching for. Just go to Service360!

Service360 Way

We believe that it should not be hard to have good service documentation.

With Service360 and DevOps Service Docs Framework we offer to the community our take on the path to the holy grail: good service documentation.