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