DevOps Service Documentation Framework

Service360 DevOps Service Documentation Framework consists of 2 pillars:

• documentation layout
• audit procedure

Documentation layout ensures that all essential documentation is present and is comprehensive, yet graspable and complete.

Audit procedure makes sure that documentation is up-to-date.

Documentation framework is integrated with the Service360 platform and in case some parts of it need attention (something is missing, gets outdated, and such) risk alert will be raised.

As usual it is NOT mandatory to use Service360 to benefit from the DevOps Service Documentation Framework. Feel free to apply it and use it on your own. Though with Service360 it is just more convenient. :)

Documentation Layout

TL;DR ServiceBoilerplate is a great way to familiarize yourself with the documentation layout.

Complete service documentation according to Service360 standard must provide information about:

• Service responsibilities, ownership, status and tech stack it is built on (Service Passport - root README.md file)
• Cross-service dependencies (Service Dependency Graph - deps.s360.puml)
• Release/rollback procedure (docs/release)
• Development setup / common pitfalls (docs/development)
• Monitoring/alerting setup (docs/monitoring)
• Disaster recovery procedure (docs/disaster-recovery)
• Common manual operations runbooks (docs/how-to)
• Post-mortem reports (docs/post-mortem)
• Service audit reports (docs/audit)
• Architectural Decision Records (docs/adr)

.
├── docs
│   ├── adr
│   │   └── ...
│   ├── audit
│   │   ├── ...
│   ├── development
│   │   └── ...
│   ├── disaster-recovery
│   │   └── ...
│   ├── how-to
│   │   └── ...
│   ├── monitoring
│   │   └── ...
│   ├── post-mortem
│   │   └── ...
│   └── release
│       └── ...
├── README.md
└── deps.s360.puml

Based on the type of your application (service, library, mobile, etc) not all of those docs would make sense and are required. (For example disaster-recovery of library would not make much sense, or development documentation for the external service).

For the most of the contents of the docs/ folder Service360 does not do any assumptions on the contents of the files inside. Though several suggestions on formats are proposed in the ServiceBoilerplate.

Service Audit

In order to make sure service documentation is up-to-date, complete, and still makes sense Service360 Service Documentation Framework couples documentation layout with the Service Audit procedure.

Service Audit is the service review process designed to help maintain service documentation in the most up-to-date and useful way.

Service360 offers a simple checklist template of the Service Audit procedure, though it is completely up to you what to really include into the audit. You can make the procedure as basic or as comprehensive as you want as long as you make sure that documentation check is included into it.

Service360 expects all Service Audits to be documented as a report and stored in the service repository in the docs/audit folder. No assumptions are made on the structure of the report with the exception of the filename. Audit file should be named following YYYY-MM-DD.md pattern. This is needed to detect the date of the last audit.

Date of the last audit is used to determine “freshness” of the documentation. If there is no audit documentation found, then Service360 assumes that date of last audit is the date of the first contribution (service creation date).

Service360 offers the following alerts tied to the ServiceAudit:

• No alert: Less than 180 days since last audit
• Low level alert: More than 180 but less than 360 days since last audit
• Medium level alert: Over 360 days since last audit

As you can see it is suggested to do Service Review every half a year (or at least once a year). From our experience this is a period of time during which documentation drift accumulates enough to make sense for some dedicated time for the review and reassessment.

Links

• Great intro into ADRs