Anthony Giniers
@antogyn
@aginiers
Intro to Diátaxis
https://slides.com/antogyn/diataxis
A framework to technical documentation authoring
What are your key problems with documentation today?
My key problems
-
Absent
-
I don't know where to find it
-
I don't know where to write it
-
I don't know how to organize it
One of the key problems is...
Structure
Let's focus on the need of its users...
What's the URL of the internal GraphQL router?
Factual, objective, austere
Why did we pick GraphQL over REST?
Contextual, understanding the big picture, focus on the "why"
How do I download GraphQL schemas?
Action oriented, focused on tasks
I don't know anything about GraphQL, help!
Learning, help getting started
| If the content... | ... and serves the user's... | ... then it belongs to |
|---|---|---|
| is practical | study | a tutorial |
I don't know anything about GraphQL, help!
=> Tutorial
| If the content... | ... and serves the user's... | ... then it belongs to |
|---|---|---|
| is practical | study | a tutorial |
| is practical | work | a how-to guide |
How do I download GraphQL schemas?
=> How-to guide
| If the content... | ... and serves the user's... | ... then it belongs to |
|---|---|---|
| is practical | study | a tutorial |
| is practical | work | a how-to guide |
| is theoretical | study | explanation |
Why did we pick GraphQL over REST?
=> Explanations
| If the content... | ... and serves the user's... | ... then it belongs to |
|---|---|---|
| is practical | study | a tutorial |
| is practical | work | a how-to guide |
| is theoretical | study | explanation |
| is theoretical | work | reference material |
What's the URL of the internal GraphQL router?
=> Reference material
Quiz time
A tutorial is a learning experience
It takes the reader by the hand through a series of practical steps to realise a project
A tutorial
- is repeatable
- instils confidence
- must result in success every time
- is concrete and particular
abstraction, generalisationexplanationschoicesinformation
Anti-pedagogical temptations
A how-to guide is a recipe
It takes the reader through the steps required to complete a specific task
A how-to guide
- has practical utility
- has a clear objective
- serves the already-competent user
- imperative
- "to do this, do that"
- action and only action
- no digression, explanation, teaching
Style
It provides a technical description of the machinery
Reference material
- is reliable
- is complete
- excludes instruction and explanation
- austere and uncompromising
- neutral, objective, factual
- consistent
Style
Explanation is a discussion
It illuminates and clarifies a particular topic, discursively
Explanation
- offers context
- establishes connections
- answers to the needs of the person who wants to know more
- deepens the theoretical understanding of a craft
- the bigger picture
- history
- choices, alternatives, possibilities
- why: reasons and justifications
Style
Quiz time #2
Exercice (if we have time)
Come up with one example for each of the four concepts in a specific craft
Examples: cycling, playing an instrument, photography, playing chess....
Thank you!
Questions?