commit 5c54876ade919fc131a833e2cc1f25df885a8721
parent b708d7587b85358e41df944743ee765a07f21973
Author: neau <neau@web>
Date: Wed, 22 Jun 2022 01:48:50 +0200
empty web commit
Diffstat:
1 file changed, 25 insertions(+), 0 deletions(-)
diff --git a/documentation.mdwn b/documentation.mdwn
@@ -0,0 +1,25 @@
+Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. They are what your project needs in order to show a beginner that they can achieve something with it.
+
+* Gets the user started
+* Allows the user to learn by doing
+* Ensures the user sees results immediately
+* Focuses on concrete steps, not abstract concepts
+
+How-to guides assume some knowledge and understanding, and take the reader through the steps required to solve a real-world problem. They are recipes, directions to achieve a specific end - for example: how to create a web form; how to plot a three-dimensional data-set; how to enable LDAP authentication. How-to guides are quite distinct from tutorials. A how-to guide is an answer to a question that a true beginner might not even be able to formulate.
+
+* Solves a problem
+* Focuses on results
+* Allows for some flexibility
+
+Explanations can equally well be described as discussions. They are a chance for the documentation to relax and step back from the software, taking a wider view, illuminating it from a higher level or even from different perspectives. You might imagine a discussion document being read at leisure, rather than over the code.
+
+* Explains a choice
+* Provides context
+* Discusses alternatives & opinions
+
+Reference guides are technical descriptions of the machinery and how to operate it. They are code-determined, because ultimately that's what they describe: key classes, functions, APIs, and so they should list things like functions, fields, attributes and methods, and set out how to use them.
+
+* Describes the machinery
+* References material should be austere and to the point.
+* Structure the documentation around the code
+* Do nothing but describe
