How to effectively document a product composed of complex microservices?
I have a highly flexible software product consisting of a series of loosely coupled microservices. Each component is effective at a single job, but may be dependent on inputs from other services. It is expected that additional services will be added later.
The overall product could be considered to be something like the game Mousetrap. A practical use case for the whole product could be a complex combination of services. Maybe I have a ball-rolling-down-stairs component, but just documenting the inputs and outputs seems incomplete as only once I combine it with the kicking-foot component and the dropping-cage component does one possible overall use case of the product (catching mice) get satisfied.
What is the best way to document such dependent services?
To clarify I'm not just interested in what to document. I'd also like opinions on how to split up and structure the documentation, especially as the product gets more complex.
This post was sourced from https://writers.stackexchange.com/q/33513. It is licensed under CC BY-SA 3.0.
1 answer
I've worked on a few doc sets like that. While API reference documentation is one case where you see this problem, the problem occurs at the "module" level too.
Your question is about microservices, which take inputs and produce outputs and can be chained together. I'm going to describe a case that wasn't microservices in particular but had similar properties.
One system I documented was a development kit for plugins to an existing software system. That is, users weren't writing stand-alone things; they were writing things that would be injected into an existing system. A plugin could contain any mix of several types of components -- data visualizations, gesture definitions (for example, new drag-and-drop behaviors), web-service integrations, extensions to the system's information architecture, and more. And while you would think that everything would depend on and flow from the information architecture, there were times when the kind of visualization you were creating or the particulars of a web service informed IA.
The approach I took, which our users found helpful (yes, actual user feedback!), was threefold:
I documented each functional area independently, but cross-linked topics where appropriate. For example, data visualizations depend on the IA, but I didn't repeat information about the IA in the data-vis doc; I linked to it. Even if you're delivering PDFs instead of HTML, and they're too large to reasonably combine in one document, you can reference other documents.
I wrote a substantial introductory document that described the plugin system (and explained how to assemble them), introduced each of the functional areas, and presented an example more substantial than "hello world" but still simple enough to follow.
I accompanied the documentation with a suite of runnable examples that used various combinations of the components at various levels of complexity. I cannot over-emphasize the importance of varied, runnable, realistic examples for a system like this. You can't (and shouldn't) show every possible combination, but you can show groupings that make sense together. Users copy examples, so this is a good way to demonstrate best practices.
To summarize: document the pieces so that they stand alone as much as possible, write documentation that ties the pieces together, and show real examples.
0 comment threads
0 comment threads