WTFM
Where's
the
F******
Manual⁈
Something I need to do
Something I need to do
How to do something
This describes how to do something in a completely different context.
Something I need to do
How to do something
This describes how to do something in a completely different context.
Something 0.1
In the old times there was this very complicated process to do something.
This explains it in all detail, but it won't work any more.
Something I need to do
How to do something
This describes how to do something in a completely different context.
Something 0.1
In the old times there was this very complicated process to do something.
This explains it in all detail, but it won't work any more.
About Something
Here's a good explanation about something in general.
It is not not helpful, but contains way too much information you don't need at all.
How do did something in the whatever-service
A team-internal documentation that actually helps, but is not well written.
Something I need to do
How to do something
This describes how to do something in a completely different context.
About Something
Here's a good explanation about something in general.
It is not not helpful, but contains way too much information you don't need at all.
Something 0.1
In the old times there was this very complicated process to do something.
This explains it in all detail, but it won't work any more.
Why is it so hard?
Exists
Mandatory Structure
Users / Purpose
Functionality
Performance
Code Style Guide
Usability
🎉
👏
🍾
🥳
🙌
Feedback 😍😃😕😡
Followup requests
Usage metrics 📊📈
User reviews
🧐
Pride 💪
Exists 📋✔
🧐 Compliance
Reviews
🥱
Documentation is a Duplication
Evolutions
Duplicates
a Change here…
…needs to be done here…
…and here as well
a Change here…
…and here as well
…needs to be done here…
Duplicates
…and here as well
Duplicates
a Change here…
…needs to be done here…
colocated, easy to change
verify code
⇒ automatically checked
well known, but not loved
we have one⁉
with distance, reduce detail
be aware of all the docs
get rid of as many as possible
Not-Owned Documentation
decribe how the code works
…and why
but may also decribe how dependencies work
…needs to be reflected here
but may also decribe how dependencies work
so a change here…
use links to external docs whenever possible
How to know what to document?
Collect what you (as a team) know.
1
Think about who needs that information, and why
2
Think about who needs that information, and why
2
Think about who needs that information, and why
2
Think about who needs that information, and why
2
Think about who needs that information, and why
2
Think about who needs that information, and why
2
Order your knowledge stories by demand and change rate
3
keep it informal
"camp fire knowledge"
for now
make it easy for the writers (e.g. generate from code)
make it easy for the readers (e.g. redundant)
document it
high demand
high change rate
low demand
low change rate
Order your knowledge stories by demand and change rate
3
keep it informal
"camp fire knowledge"
for now
make it easy for the writers (e.g. generate from code)
document it
high demand
high change rate
low demand
low change rate
Order your knowledge stories by demand and change rate
3
keep it informal
"camp fire knowledge"
for now
make it easy for the writers (e.g. generate from code)
high demand
high change rate
low demand
low change rate
Order your knowledge stories by demand and change rate
3
keep it informal
"camp fire knowledge"
for now
high demand
high change rate
low demand
low change rate
Order your knowledge stories by demand and change rate
3
high demand
high change rate
low demand
low change rate
Decide where to document it
4
Decide where to document it
4
Devs have access to code repos.
Refactorings will happen in the code.
Decide where to document it
4
Decide where to document it
4
Decide where to document it
4
Decide how to document it with Diátaxis
5
5
Decide how to document it with Diátaxis
Users want to acquire a skill
Content informs
Action
Users want to apply a skill
Content informs Cognition
Tutorial
Users want to acquire a skill
Content informs
Action
Tutorial
Users want to acquire a skill
Content informs
Action
Users want to apply a skill
Content informs Cognition
5
Decide how to document it with Diátaxis
How To Guide
Content informs
Action
Users want to apply a skill
How To Guide
Users want to acquire a skill
Content informs
Action
Users want to apply a skill
Content informs Cognition
Tutorial
5
Decide how to document it with Diátaxis
Reference
Content informs Cognition
Users want to apply a skill
Reference
How To Guide
Content informs
Action
Users want to apply a skill
Tutorial
5
Decide how to document it with Diátaxis
Users want to acquire a skill
Content informs Cognition
Explanation
Users want to acquire a skill
Content informs Cognition
Explanation
Reference
How To Guide
Users want to acquire a skill
Content informs
Action
Users want to apply a skill
Content informs Cognition
Tutorial
5
Decide how to document it with Diátaxis
What may we achieve?
We are aware that documentation is a deliverable that needs to be maintained
By creating & prioritizing knowledge stories, we know
- who we needs the docs
- what exactly they need to know, and
- why the need it
We are aware that documentation is a deliverable that needs to be maintained
By creating & prioritizing knowledge stories, we know
- who we needs the docs
- what exactly they need to know, and
- why the need it
The Diátaxis framework gives us a good compass to choose a good form of documentation
We are aware that documentation is a deliverable that needs to be maintained
Thank you! 🙏
Get the slides 👆
Rate the session 👇
Thank you! 🙏