: 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

Vote Up Vote Down

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)

Vote Up Vote Down

Much depends on how the microservices are packaged for the consumer. If users can mix and match, you need to document each microservice separately, but include “meta” information for the user to combine the chutes and ladders (to mix game analogies) together. This part may take some insight from product management and actual users, and may take the form of use cases, examples, road maps, and the like.

There probably won’t be a linear path through the entire product set for every reader. Keep the documentation organized in topic-based modules to help various readers navigate the topics for their own needs.

(0)

Vote Up Vote Down

What you just described is almost every Web based REST API. Those are nothing more than a series of calls, sometimes into the hundreds or thousands, that the developer has to put into a meaningful sequence. This also goes for client-based APIs, too.

The answer is tedious but not complex. First, every call has to be documented individually. Developers have to understand what the call does, parameters, side affects, and caveats. That's the easy part. Then it has to be explained how these parts fit together. This gets a little harder. This may be done through several comprehensive samples, a getting started, or comprehensive how to articles. You may not be able to document all the cases, but you can document enough so that they could extrapolate into new situations. You're an API documentation writer now.

In doing this, keep in mind a useful approach and write for yourself. That means, writing to yourself while you learn the product. If you need to learn something, others will need to know that, too. If you find something confusing, they will. What did you find useful while learning?

Finally, review others' APIs. A good starting place is ProgrammableWeb.com.

(0)