Documentation Overview
DASSIT™ documentation is structured around four pillars that cover the different functions you may need to reach:
| Tutorials | How-To guides | References | Themes | |
|---|---|---|---|---|
| Orientation | Learning | Goal | Information | Understanding |
| Must | Allow the newcomer to get started | Show how to solve a specific problem | Describe the machinery | Explain |
| Form | A lesson | A step series | Dry description | Discursive explanation |
| Analogy | Teaching a child how to cook | A recipe in a cookery book | A reference encyclopedia article | An article on culinary social history |
Tutorials
Section titled “Tutorials”Tutorials are useful-for-beginners, easy-to-follow, meaningful and robust, and kept up-to-date lessons that take the reader by the hand through a series of steps to complete a task, showing a beginner that they can achieve something with DASSIT™
Tutorials are wholly learning-oriented, and specifically, they are oriented towards learning HOW rather than learning WHAT
The tutorials are responsible for what the newcomer will do by executing a series of actions to achieve some end, so, after having it done, the learner is in a position to make sense of the rest of this documentation
How-To guides
Section titled “How-To guides”How-to guides take the reader through the steps required to solve a real-world problem, acting like recipes or directions to achieve a specific end
They are wholly goal-oriented and quite distinct from tutorials and must not be confused with them:
- A tutorial is what DASSIT™ team decides a beginner needs to know
- A how-to guide is an answer to a question that only a user with some experience could even formulate
In a how-to guide, we assume some knowledge and understanding from you
References
Section titled “References”Reference guides are technical descriptions strictly focused on describing DASSIT’s machinery that are information-oriented documents designed to be simple and concise
Key characteristics include:
- Sole Purpose: To describe the code and its technical operation
- Scope: They may include usage examples but they don’t explain basic concepts or how to achieve specific user goals (unlike how-to guides)
Themes
Section titled “Themes”Themes (also called explanations or discussions) are understanding-oriented documents designed to clarify context and illuminate specific topics
They provide a discursive, high-level perspective that steps back from the immediate code, making them suitable for reading at leisure
Key characteristics and challenges include:
- Arbitrary Scope: Unlike tutorials (learning goals) or reference guides (machinery), explanations are not defined by specific tasks or code, but their boundaries are determined solely by what the writer chooses to cover
- Often Neglected: These sections are rarely explicitly created; instead, information is often scattered or hidden under vague headings like ‘Background’ or ‘Key Topics’