0

I would like to write a tutorial for a large Application Programming Interface, let me call that way. It is a library of many elements, in the thousand range. Obviously, only part of it is frequently used but you never know if an arcane element is needed for your problem.

Is there a standard way how to tackle such a challenge?

3
  • Do you aim to cover the entire API in your tutorial, or pick only popular topics? The former is usually done by software vendor (either they do it themselves or hire someone to do it), the latter is commonly done in numerous blogs around the internet (for example, baeldung.com for Java).
    – Alexander
    Mar 31 at 17:12
  • I want a good introduction that makes you able to understand the whole, and write about every element at least a bit. It should have a story so that people would read it from cover to back.
    – Gergely
    Apr 1 at 8:52
  • 1
    Copy from a source you like -- check documentation for similar APIs and see how they handle it. There is probably some similar programming interface you can get documentation for. Usually these have an introduction about using the the API in general, and then an alphabetical reference section where each command or class is described in a standard format with labels like Command, Parameters, Error Codes or Exceptions, Examples.
    – user8356
    Apr 1 at 14:22
2

The organizations like Software Engineering Institute at Carnegie Mellon University have defined standards for topics like documenting library architectures. You can look there for the guidelines.

For tutorials, I'd believe the only standard is clarity and fullness. For a small API, well documented examples and function or class definitions will suffice because it is easy for the author to evaluate if they've covered everything in reasonable detail.

For a large API, having a defined standard for documentation is a terrific idea because it will permit the authors to know when they've provided sufficient information. The documentation for the boost libraries is a good example to follow.

Good documentation follows the same general outline as a thesis or academic paper: SUMMARY BACKGROUND CONTENT and FUTURE WORK.

The SUMMARY describes the purpose of the API or sub-library. T

The BACKGROUND might be something as simple as a HELLO WORLD program using the API or sub-library.

The CONTENT is the deep dive providing an escalating series of tutorials on getting the most out of the library. This is best when it starts simply, maybe extending the HELLO WORLD program and builds up.

FUTURE WORK is optional and its purpose is to describe how this API is planned to be extended in the future. This provides a dual benefit since it shows the end users that this library isn't expected to be dead end like so many that litter the interweb and sparks a conversation about ideas between developers and users about how to improve the organization of the API.

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.