Writing the docs
Summary
Build a knowledge base that compounds in value over time. How? Utilise the four modes of documentation outlined in the Diátaxis framework to ensure your notes have a clear, actionable purpose.
The Framework
Poorly structured documentation can take a lot of time to read, understand and apply. However, 'documentation' is not limited to that new tool or technology you are trying to learn. Everytime we take conduct some research, try to learn something new and take some notes, we are authoring our own documentation.
The Diátaxis framework of technical documentation authoring, aims to solve this problem, by identifiying:
four modes of documentation - tutorials, how-to guides, technical reference and explanation...each of these modes (or types) answers to a different user need, fulfils a different purpose and requires a different approach to its creation.
Diátaxis
These different modes are useful for various stages of learning skills and applying knowledge.
The four modes are:
- Tutorials (Learning-oriented)
- How-to Guides (Task-oriented)
- Explanation (Understanding-oriented)
- Reference (Information-oriented)
Using the Framework
Why?
Understanding our needs and how they change in the different stages of learning and using technologies can help when structuring notes. Well structured notes generally make it easier to:
- learn things quickly
- find notes in the future
- make notes actionable
How?
Write notes that align with the way you intend to use the information. The easiest way to is to preface each note with a title that indicates its type.
A how to guide will probably have a title like:
How to write getStaticProps to fetch the data for each blog post.
Such a note should have clear steps, and should only contain information that contributes to the achievement of the task at hand.
A note in the mode of understanding will have a title like:
Why were single-page applications invented?
It prompts us to dig deeper into a specific subject and explain some meaning.
A reference note is usually more dry and technical, easy to quickly revisit during our work.
Syntax for writing condition-controlled loops in JavaScript
I rarely use the tutorial documentation mode in my personal knowledge base because it is most useful when you are brand new to something. Tutorials help you broach a subject, but don't usually need to be referenced in future as you become more advanced.
Next steps
If you are interested, I would highly recommend checking out https://diataxis.fr/. The pages that explain each of the documentation modes, what they are and more importantly what they are NOT can be helpful in guiding your own practice of writing notes that have clear intentions.