Meta tags:
author= Daniele Procida;
description= The best way to get started with Diátaxis is by applying it to documentation problems.;
Headings (most frequently used words):
diátaxis, the, start, here, in, five, minutes, four, kinds, of, documentation, map, compass, working, do, what, you, like, get, started, tutorials, how, to, guides, reference, explanation,
Text of the page (most frequently used words):
the (71), you (40), and (33), #diátaxis (25), that (21), how (18), reference (16), documentation (16), #explanation (15), user (15), what (14), guides (12), tutorials (12), map (10), more (9), when (9), guide (9), four (8), with (8), need (8), work (8), not (8), different (8), get (7), compass (7), this (7), can (7), but (7), are (7), like (6), kinds (6), will (6), from (6), thing (6), there (6), skill (6), action (6), tutorial (6), detail (6), started (5), start (5), here (5), read (5), each (5), them (5), helps (5), help (5), for (5), things (5), their (5), should (4), have (4), one (4), doing (4), don (4), then (4), could (4), way (4), informs (4), problems (4), make (4), serve (4), who (4), learner (4), use (4), needs (4), instructor (4), light (4), dark (4), mode (4), five (3), minutes (3), applying (3), website (3), problem (3), just (3), right (3), now (3), even (3), find (3), around (3), actually (3), however (3), which (3), see (3), acquisition (3), cognition (3), application (3), study (3), other (3), concerned (3), does (3), purpose (3), contain (3), they (3), through (3), lesson (3), working (2), page (2), home (2), next (2), most (2), guidance (2), question (2), everything (2), nothing (2), practice (2), give (2), about (2), doesn (2), approach (2), think (2), create (2), idea (2), small (2), would (2), might (2), simple (2), workflow (2), must (2), serves (2), content (2), understand (2), your (2), useful (2), hand (2), between (2), often (2), https (2), because (2), depth (2), using (2), belongs (2), propositional (2), knowledge (2), rather (2), than (2), its (2), directions (2), picture (2), why (2), understanding (2), architecture (2), material (2), competent (2), correctly (2), software (2), always (2), addresses (2), practical (2), written (2), has (2), example (2), student (2), something (2), sense (2), auto (2), copyright, daniele, procida, previous, want, eventually, probably, comes, alive, value, turn, point, else, ever, after, least, made, improvement, clue, only, keep, extensively, elaborated, theory, subscribe, require, commitment, pursue, final, end, believe, exam, wholly, pragmatic, matters, people, better, insight, seems, worthwhile, yourself, true, repeat, decide, improve, ask, any, improved, consider, front, literally, haven, yet, very, belong, nearly, eye, catching, puzzling, over, move, forward, looking, going, makes, stand, out, creating, clarify, own, intentions, sure, two, ways, tell, sort, tool, case, kind, knows, crossing, blurring, boundaries, described, heart, vast, number, list, conceptual, arrangement, shows, related, distinct, relationships, summarised, writers, anxious, students, overload, distracting, unhelpful, much, minimal, safer, link, article, ready, secure, communication, encryption, know, realm, circle, subject, opinions, take, perspectives, put, bigger, joins, together, answer, explanatory, provide, context, background, difference, where, possible, reflect, structure, describing, method, part, class, certain, module, expect, same, relationship, too, marine, chart, used, ship, navigator, plot, course, equally, well, investigating, judge, neutral, sufficiently, interpret, facts, order, accurate, complete, reliable, information, free, distraction, interpretation, theoretical, technical, description, motion, photography, troubleshooting, deployment, configure, frame, profiling, store, cellulose, nitrate, film, already, expected, able, done, contrast, providing, situation, real, world, goal, special, difficulty, condemned, absent, monitor, correct, mistakes, somehow, present, instruction, alone, someone, tried, teach, learn, driving, good, develop, skills, confidence, let, game, python, takes, learning, experience, under, designed, encounter, responsible, safety, success, completely, core, fundamentally, identifiable, respond, brief, primer, section, contains, links, refer, reflecting, encountered, fact, recommend, best, treat, handbook, toolbox, polski, english, back, top, news, updates, translate, colophon, quality, foundations, skip, expand, menu, contents,
Text of the page (random words):
start here diátaxis in five minutes diátaxis contents menu expand light mode dark mode auto light dark in light mode auto light dark in dark mode skip to content diátaxis home start here applying diátaxis tutorials how to guides reference explanation the compass workflow understanding diátaxis foundations the map quality tutorials and how to guides reference and explanation colophon help translate diátaxis news updates back to top english en polski pl start here diátaxis in five minutes treat this website as a handbook or a toolbox that you make use of when you need it you don t need to read everything on this website to make sense of diátaxis or to start using it in practice in fact i recommend that you don t the best way to get started with diátaxis is by applying it to something however small read this page for a brief primer each section contains links to more in depth material refer to that when you need it when you re actually at work or reflecting on the documentation problems you have encountered the four kinds of documentation the core idea of diátaxis is that there are fundamentally four identifiable kinds of documentation that respond to four different needs the four kinds are tutorials how to guides reference and explanation each has a different purpose and needs to be written in a different way tutorials tutorials in more detail why tutorials are completely different from how to guides a tutorial is a lesson that takes a student by the hand through a learning experience a tutorial is always practical the user does something under the guidance of an instructor a tutorial is designed around an encounter that the learner can make sense of in which the instructor is responsible for the learner s safety and success a driving lesson is a good example of a tutorial the purpose of the lesson is to develop skills and confidence in the student not to get from a to b a software example could be let s create a simple game in python the user will learn through what they do not because someone has tried to teach them in documentation the special difficulty is that the instructor is condemned to be absent and is not there to monitor the learner and correct their mistakes the instructor must somehow find a way to be present through written instruction alone how to guides how to guides in more detail a how to guide addresses a real world goal or problem by providing practical directions to help the user who is in that situation a how to guide always addresses an already competent user who is expected to be able to use the guide to help them get their work done in contrast to a tutorial a how to guide is concerned with work rather than study a how to guide might be how to store cellulose nitrate film in motion picture photography or how to configure frame profiling in software or even troubleshooting deployment problems reference reference in more detail reference guides contain the technical description facts that a user needs in order to do things correctly accurate complete reliable information free of distraction and interpretation they contain propositional or theoretical knowledge not guides to action like a how to guide reference documentation serves the user who is at work and it s up to the user to be sufficiently competent to interpret and use it correctly reference material is neutral it is not concerned with what the user is doing a marine chart could be used by a ship s navigator to plot a course but equally well by an investigating judge where possible the architecture of reference documentation should reflect the structure or architecture of the thing it s describing just like a map does if a method is part of a class that belongs to a certain module then we should expect to see the same relationship in the documentation too explanation explanation in more detail understanding the difference between reference and explanation explanatory guides provide context and background they serve the need to understand and put things in a bigger picture explanation joins things together and helps answer the question why explanation often needs to circle around its subject and approach it from different directions it can contain opinions and take perspectives like reference explanation belongs to the realm of propositional knowledge rather than action however its purpose is to serve the user s study as tutorials do and not their work often writers of tutorials who are anxious that their students should know things overload their tutorials with distracting and unhelpful explanation it would be much more useful to give the learner the most minimal explanation here we use https because it s safer and then link to an in depth article secure communication using https encryption for when the user is ready for it the diátaxis map the four kinds of documentation and the relationships between them can be summarised in the diátaxis map the map in more detail diátaxis is not just a list of four different things but a conceptual arrangement of them it shows how the four kinds of documentation are related to each other and distinct from each other crossing or blurring the boundaries described in the map is at the heart of a vast number of problems in documentation the diátaxis compass as you can see from the map tutorials and how to guides are concerned with what the user does action reference and explanation are about what the user knows cognition on the other hand tutorials and explanation serve the acquisition of skill the user s study how to guides and reference serve the application of skill the user s work but a map doesn t tell you what to do it s reference to guide your action you need a different sort of tool in this case a kind of diátaxis compass the compass in more detail the compass is useful in two different ways when creating documentation it helps clarify your own intentions and helps make sure you re actually doing what you think you re doing when looking at documentation it helps understand what s going on in it and makes problems stand out the compass is not nearly as eye catching as the map but when you re at work puzzling over a documentation problem it s what will help you move forward if the content and serves the user s then it must belong to informs action acquisition of skill a tutorial informs action application of skill a how to guide informs cognition application of skill reference informs cognition acquisition of skill explanation working there is a very simple workflow for diátaxis diátaxis as a guide to work consider what you see in the documentation in front of you right now which might be literally nothing if you haven t started yet ask is there any way in which it could be improved decide on one thing you could do to it right now however small that would improve it do that thing and then repeat that s it do what you like you can do what you like with diátaxis you don t have to believe in it and there is no exam it is a wholly pragmatic approach i think it s true but what matters is that it actually helps people create better documentation if you find one idea or insight in it that seems to be worthwhile help yourself to that there is an extensively elaborated theory around diátaxis but you don t need to subscribe to it or even read about it diátaxis doesn t require a commitment to pursue it to a final end you can do just one thing right now and even if you do nothing else ever after you will at least have made that one improvement in practice what you will find is that each thing you do will give you a clue as to the next thing to do you only need to keep doing them get started at this point you have read everything you need to get started with diátaxis you can read more if you want and eventually you probably should but you will get the most value from the guidance in this website when you turn to it with a problem or a question that s when it comes alive next applying diátaxis previous home copyright daniele procida on this page start here diátaxis in five minutes the four kinds of documentation tutorials how to guides reference explanation the diátaxis map the diátaxis compass working do what you like get started
|
