: Re: 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

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.

Load Full (0)

: Git is like a backend database, so that means there can be a frontend. There are plenty of frontends, such as BitBucket. With these you can link to commit pages. Chances are your git administrator,

@Margaret427

Load Full 0 Comments

: Are there valid reasons to write Java Annotation (or .NET XML Documentation) for private methods? At this point, many languages have some "standard" format for writing documentation for individual

@Margaret427

Load Full 1 Comments

: The best translation is often not word-for-word, you need to get across the overall sense of what is being said. This may not always be feasible for instant translators, but you can do better

@Margaret427

Load Full 0 Comments

: Third person into first person as the protagonist becomes the same entity as the narrator I'm attempting to write a sci-fi novel in a dystopian future baring semblance to that within 1984. I'm

: Re: 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

More posts by @Margaret427

: Git is like a backend database, so that means there can be a frontend. There are plenty of frontends, such as BitBucket. With these you can link to commit pages. Chances are your git administrator,

: Are there valid reasons to write Java Annotation (or .NET XML Documentation) for private methods? At this point, many languages have some "standard" format for writing documentation for individual

: The best translation is often not word-for-word, you need to get across the overall sense of what is being said. This may not always be feasible for instant translators, but you can do better

: Third person into first person as the protagonist becomes the same entity as the narrator I'm attempting to write a sci-fi novel in a dystopian future baring semblance to that within 1984. I'm

Login to post a comment!

0 Comments

Back to top