Post History

Source: https://writers.stackexchange.com/a/33659
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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.

Original score: 4