Thread by @juristr

Documentation is hard. @meeroslav referred me to diataxis.fr, probably the 1st categorization of structuring technical docs that immediately made sense to me.

It approaches docs from these 4 angles.

here’s me paraphrasing some things to remember 🧵👇

#devrel

@meeroslav Tutorials are learning oriented. They provide a path for the learner to follow, exercise and comprehend. They should not directly teach, but provide opportunities to learn. They are not intended to create experts, but create interest and lay the basis for exploring more.

@meeroslav Tutorials vs How Tos is like a cooking lesson vs a recipe.
Both come with concrete steps but one is meant to teach/learn while the other is a guide to reach a desired outcome in the most direct and efficient way.

@meeroslav How-tos are the recipes. They don’t teach you cooking, it is assumed you already have some basic knowledge about that. It gives a concise step-by-step guidance on how to reach a specific end goal.

@meeroslav Explanation/Concept articles shed some light to a topic from different angles, approaching it from a higher up view. Like “about computation caching”. They don’t instruct but provide connections, context etc. Like a book on food/cooking throughout history

@meeroslav References do not care about the user perspective, they are about the product. Like APIs, CLI arguments and commands, low-level technical details about the machinery.