Skip to main content

Standardize the Location of Microservice Documentation

Context​

Microservices are being adopted. There are multiple microservices with their own APIs and documentation. There is no standardized way how to document a microservice.

Problem​

  • There are several locations where you need to look to find the documentation since every microservice handles it differently.

Solution​

Standardize the location where to find the documentation. The location of the documentation should be consistent so you only have to look at one place to find the documentation, or at least have an entry point of the documentation pointing to further resources.

Examples for possible locations:

  • In source control tool alongside with the microservice code.
  • API registry serving the documentation (like in SOA).
  • Tool in your ecosystem that allows to organize the documentation in a central place (e.g. Confluence, or a Wiki).
  • Central meta-model / virtual objects containing or pointing to fine-grained documentation.

This technique is a specialization of establishing standards.

Maturity​

Proposed, to be evaluated.

Sources of Evidence​

L46:

  • context: enterprise
    • API registry / repository (pendant to SOA service registry/repository)
    • make interfaces exposed to consumers visible
    • standardized format
    • access controlled
    • search and retrieval capabilities => design time lookup of API specs
    • central location for governance of API portfolio
  • Should contain more than only API
    • Status
    • Ownership
  • Discoverability of interfaces
    • look up and find interfaces without knowledge of underlying technology implementation or location

L52:

  • enterprise context, EA mini descriptions
  • M1 contains meta-data of microservice
    • purpose
    • API endpoints
    • usage costs
    • communication channels

L53:

  • in context of IoT systems
  • "virtual object" per microservice with "introspect method"
    • detailing all virtual objects and service interfaces (with mapping to protocols) of microservice
    • plaintext for developers or HTML/XML for rendering, or OWL/RDF for human and machine readability

Interview A:

  • Thinking about how to organize documentation
    • README in repo
    • vs. docs in confluence / Jira ticket
    • vs. generated API docs
  • Decision: use the README versioned in git
    • => changelog
    • goes into summarizing documentation and operation handbook
    • Linked to Jira tickets for traceability

Interview D:

  • Self-documenting microservices
    • REST endpoint with content-type HTTP => Rest maturity level XY
  • Standarize
    • What to document
    • Where to find it (discoverability of APIs)
      • believes there needs to be an additional communication channel