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, generalisation
  • explanations
  • choices
  • information

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?