11

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.

migrated from techcomm.stackexchange.com Feb 20 '18 at 15:18

4

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.

5

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.

  • I've just added a clarification. Your answer clearly states what to document, but I'm also interested in the split and structure of the information - hence the information-architecture tag. – Jason Fox Feb 11 '18 at 17:42
4

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.