Michael Kutz
Quality Engineer at REWE digital, Conference Speaker about QA & Agile, Founder of Agile QA Cologne meetup, Freelance QA Consultant
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 to do 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 😍😃😕😡
Follow-up requests
Usage metrics 📊📈
User reviews
🧐
Pride 💪
Exists 📋✔
🧐 Compliance
Reviews
🥱
Historic Artifacts are not Documentation
Evolutions ≠ Documentation
Documentation is a Duplication
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…
collocated, 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
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
Order your knowledge stories by demand and change rate
3
keep it informal
"bonfire 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
"bonfire 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
"bonfire 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
"bonfire 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
Devs have access to code repos.
Refactorings will happen in the code.
Architects don't crawl repos.
Decide how to document it with Diátaxis
5
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
Explanation
Reference
Tutorial
What may we achieve?
We are aware that documentation is a deliverable that needs to be maintained
AI reads too and less wary of old docs
By creating & prioritizing knowledge stories, we know
- who needs the docs
- what do they need to know, and
- why do they need it
We are aware that documentation is a deliverable that needs to be maintained
AI reads too and less wary of old docs
By creating & prioritizing knowledge stories, we know
- who needs the docs
- what do they need to know, and
- why do they 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
AI reads too and less wary of old docs
Thank you! 🙏
Get the slides 👆
Thank you! 🙏
"Agents can read the code. Why bother?"
- Code shows what it does, not what it should do
- Code doesn't show why, or what we already ruled out
- Tests show what was promised, and fail when it's broken
- Docs and tests are the context agents can't regenerate
WTFM – Where's the F****** Manual
By Michael Kutz
WTFM – Where's the F****** Manual
Key Learnings: 1. Understand what makes writing documentation so daunting. 2. Acquire some simple guidelines and techniques to detect knowledge that needs to be documented in what way. 3. Learn how to make writing and maintaining documentation rewarding and enjoyable.
