The perfect content structure will guide the reader from a complete beginner to an expert in easy-to-understand steps.
If the reader has no prior knowledge, the Overview (index.adoc) should provide them with an overview of the library, explaining:
-
What it is
-
Why they should use it
-
When it is appropriate to use it
Once they know what the thing is, they should be instructed how to install it.
-
Where can the user download any dependencies?
-
Are any steps needed to build any dependencies from source?
-
What steps are needed to install the library?
-
Single instance?
-
Installing on a cluster
-
Docker? Cloud? K8s? etc
-
Once the thing has been installed, the reader will need to know how to use it. By the end of the tutorial, the reader should have the confidence to use the library without any assistance.
THe tutorial should provide concrete examples on how to use tje
Given a concrete example, the tutorial should explain
The analogy is teaching a child how to cook.
-
tutorial.adoc: Allow a newcomer to get started with the library-
Assume that the reader has no prior knowledge of the library
-
At the end of the article they should have the confidence to use the library on their own
-
The user should learn by doing,
-
-
how-to-guide.adoc** -
graph-app.adoc** -
Manual/Reference:
The style of the content is heavily influenced by the following: