7

If this is user-facing documentation, then make up a data dictionary that describes the tables and columns with supplementary blurbs about the meaning of the data (e.g. the meanings of specific values in a column). This can be a straightforward HTML document with the supplementary descriptions as text. If you need to produce E/R diagrams then Visio ...


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 ...


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 ...


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 ...


2

This is not based on studies. It is instead just the subjective experience of plainly and painstakingly having to read through documentations of different sorts throughout the years. Documentation is mainly written for the users of the technology. These have typically different and varying skills. You need to identify these levels before you can address ...


2

It depends on the medium. I just looked through the example you provided in the comment section and it seems to me like the non-choices basically do the same that the normally limited space in a text box would do: they give the reader a couple sentences at most before he has to proceed with the standard "progress" methos - in your example clicking on the ...


2

It depends on your audience. Blessed Geek suggested UML enumeration, but this assumes that the users understand UML. Your question shows that you know technology well enough to know the capabilities of your users. Writers often use Javadoc or Doxygen to generate API documentation because those tools easily generate new docs when the API itself changes. ...


Only top voted, non community-wiki answers of a minimum length are eligible