What does Service360 do?

Service360 scans your codebase repositories and collects data from a set of files with predefined structure. That information later is compiled into insightful up-to-date reports which allows you to make reasonable decisions and not just wild (or educated) guesses.

A lot of data can be extracted from the repositories themselves but with a handful of specially formatted files with metadata value of the collected data increases exponentially.

Service360 introduces several new (though simple) concepts which provide such metadata. 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

Code repositories enhanced by that data allow us to provide high quality up-to-date service, team, and tech documentation.

Documentation challenge

One of the arguably biggest challenges with the documentation in IT is trust. How up-to-date is this documentation? Can you still use it? Will it have an answer on your question or is it simpler to go and ask around?

There are multiple factors which contribute to an actuality 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 one who maintains 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 be integrated into the usual development flow: be reviewed for being up-to-date during code review, for example. And this is ways easier to achieve if documentation resides in the same codebase repository as the code itself.

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 (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).

What’s next?

We encourage you to check out the features that Service360 provides or go straight to the Service360 setup.

For those curious in a bit more of Service360 philosophy we have another read that says what we believe is good service documentation.