[HN Gopher] Diataxis - A systematic approach to technical docume...
___________________________________________________________________
Diataxis - A systematic approach to technical documentation
authoring
Author : OuterVale
Score : 456 points
Date : 2024-12-05 04:35 UTC (18 hours ago)
(HTM) web link (diataxis.fr)
(TXT) w3m dump (diataxis.fr)
| gavindean90 wrote:
| I've read about this approach in the past and am curious if
| anyone has any experience trying to get an organization to buy
| into it.
| szvsw wrote:
| I think this idea is so common now that it is almost the
| standard for technical documentation at this point even if
| people don't know it by that name.
| ivanche wrote:
| Yup, just do it! Whenever I write a new piece of docs I try to
| fit it into one of four categories. Whenever I find docs
| written by someone else and they're all over the place, I
| message them and say "Hey this would be much more useful as a
| how-to" and link to this site.
| euroderf wrote:
| A frequent post to HN. It seems there is appeal in trying to
| systematize the entire idea of TC. I'd like to see this extended
| to three dimensions.
| simplify wrote:
| What third dimension would you add?
| euroderf wrote:
| Fair question. I've read a couple of critiques of Diataxis
| that suggest additional boxes.
|
| FAQs and "Gotchas" need a "home box". So do gists. Maybe a
| third dimension would be something like "degree of curation"
| or "need for taxonomy and organisation" ?
|
| FWIW... DITA has concepts, tasks, & references - and AFAICT
| these map fairly nicely to Diataxis.
| DanieleProcida wrote:
| FAQ lists are the equivalent of the box in my garage where
| I put things when I've been told to get them out of the
| house, and I can't actually be bothered to put them in the
| right place.
| taneliv wrote:
| Depth?
|
| Like, three line basic how-to vs. one that shows how to (!)
| achieve something more complex, or not intuitively possible
| to perform with the tool being documented. Explanations that
| only tell you why you would not want to use the tool, sort of
| a laundry list of things that you can't or shouldn't be doing
| with it, and should be using something else, as opposed to a
| comprehensive look into how (or why) the tool works, and how
| it is better than competition, for example.
|
| Not sure if that makes sense from a more systematic point of
| view, but it could easily help structure your documentation:
| "The Tutorial" and below it "list of additonal advanced and
| obscure mini-tutorials".
|
| This is not to say anything about the length of each
| document, but naturally shallower ones could often be
| shorter.
| riffic wrote:
| and I'll upvote it every time it comes up.
| perlgeek wrote:
| A natural third dimension is language. If your user base is
| very international, you might need most of these documents in
| multiple languages.
| euroderf wrote:
| User interface language is orthogonal to ebberyting.
| remram wrote:
| For every dimension you add, you double the amount of docs you
| have to write.
| euroderf wrote:
| You double the number of document _types_. But if it helps,
| it helps.
| pastage wrote:
| I often get stuck changing from reference to explanation in the
| middle of wirintg, so this is a great guide. Having a small How-
| To example in every reference entry for a API endpoint might be
| good, but you need to keep them seperate and concise, do not
| start with explanations.
|
| Here is a extract from Ubuntus page about this:
|
| > Writing security reference documentation, you will know that
| you should be producing clear and simple statements of fact.
| Explanation of a security feature or function, or showing how to
| use it - those don't belong here. There is a place for them: a
| different place. If those things are required, then there should
| also be a security explanation topic, or a security how-to guide.
| This immediately makes life easier for the documentation author,
| who recognises that explaining and showing how-to are also
| important.
|
| https://ubuntu.com/blog/diataxis-a-new-foundation-for-canoni...
| DanieleProcida wrote:
| Examples in reference material are an excellent idea, and not
| at all in contradiction to the principles of Diataxis. An
| example illustrates - like an illustration in any other
| reference guide - and provides something concrete to help grasp
| what's being described.
|
| That's different from a how-to, talking someone through a
| problem.
| euroderf wrote:
| Golang API pages collect all examples into a list at the top.
| Maybe do the same kind of things for stuff like "Quick
| explanations" and "Warnings/Gotchas". But it would get very
| subjective and potentially very messy and unmaintainable.
| sixhobbits wrote:
| It's very popular in tech writing circles and pretty standard now
| as others have suggested.
|
| We do see people try to take it too far though and have literally
| only these four categories on their docs page, which never works
| well imo.
|
| It's mainly useful for a writer to keep in mind stuff like "it's
| a guide so focus on getting to result, not teaching" but in
| reality you don't want super hard lines. It's OK to have a bit of
| tutorial in a guide.
| zahlman wrote:
| Eh, I've found that doc pages that try to establish really hard
| lines will still fail, and end up at a high level of quality. I
| think of it like a programming principle in the "don't mutate
| global variables" or "write shorter functions" category: you
| don't have to get it completely right, but most people _really
| would_ be better off moving more in that direction rather than
| away from it.
| chefandy wrote:
| The approach works better with dedicated technical writers.
| It makes sense to have distinct user-focused goals for
| documents before they're written, and then just dig into the
| necessary parts of the software enough to make that happen as
| needed. When it's developers doing the docs, they're
| approaching it from the other end. They've got a chunk of
| code they need to cover, and reasoning about user needs is
| pretty difficult from that vantage point. Picking an approach
| vector when you don't know the airport.
| red_admiral wrote:
| I think that's a SHOULD in the send of RFC 2119: "There may
| exist valid reasons in particular circumstances to ignore a
| particular item, but the full implications must be understood
| and carefully weighed before choosing a different course."
|
| Treating a SHOULD as a MUST even when particular
| circumstances are against it, is one way to fail at a task.
|
| It's like Orwell's last rule, where many people seem to miss
| that it's the punchline of the whole essay: "Break any of
| these rules sooner than say anything outright barbarous."
| grumpyprole wrote:
| > We do see people try to take it too far though
|
| I see it as a useful guide like any methodology should be. But
| I have worked with someone who insisted the rules should be
| followed to the letter, literally not a single sentence of
| explanation in any tutorial. So yes, that is the danger of
| these systems.
| fudged71 wrote:
| I recently saw someone praising the scikit-learn documentation,
| mentioning this page specifically https://scikit-
| learn.org/1.5/modules/grid_search.html so I took the top
| section and asked Claude to classify it with this framework:
|
| > This piece appears to be primarily an Explanation with some
| elements of Reference mixed in. This documentation appears to
| be trying to serve multiple purposes, which according to
| Diataxis is not ideal. The mix makes it less effective at both
| explaining and serving as reference. Following Diataxis
| principles, this content might be better split into: 1) A pure
| explanation section about the concept and importance of
| hyperparameter tuning, and 2) A separate reference section
| listing the specific tools and methods available.
|
| > This blending of documentation types is exactly what Diataxis
| warns against when it says "Unfortunately, too many software
| developers think that auto-generated reference material is all
| the documentation required" and "The writer, intent on covering
| the topic, feels the urge to include instruction or technical
| description related to it. But documentation already has other
| places for these."
|
| > HOWEVER. Let's look at why this integrated approach works
| well in a User Guide context:
|
| > Natural Learning Flow: The documentation follows how people
| actually learn and use tools: 1) First understand what
| hyperparameters are, 2) Learn why you might want to tune them,
| 3) See what tools are available, 4) Get pointed to practical
| implementation examples
|
| > Contextual Knowledge: By integrating explanation with
| technical details, users can immediately connect concepts to
| implementation. There's no need to jump between different
| documentation sections to piece together understanding.
|
| > Progressive Disclosure: The documentation starts with
| fundamental concepts and progressively introduces more complex
| tools and considerations. This scaffolding helps users build
| understanding naturally.
|
| > Practical Value: By combining explanation with specific tools
| and methods, users can immediately apply what they're learning.
| The documentation bridges theory and practice.
| brylie wrote:
| Interesting use of an LLM to help us write better and more
| organized documentation. What prompt did you use? What are
| your thoughts on the outcome?
| hobofan wrote:
| > only these four categories on their docs page
|
| Only? For many projects having a medium quality version of just
| one of those would be an improvement.
|
| ----
|
| Where the approach hits a wall in practice I think is when
| there is a lack of interconnection between the quadrants. E.g.
| for software frameworks, if the guides lack links to the
| references for specific classes/methods (which you ultimately
| will have to use), that makes exploring the surrounding context
| a lot harder. I have a few concrete frameworks in mind where
| there is a split along the quadrants and that's one of the
| biggest annoyances about their docs.
| scott_w wrote:
| > We do see people try to take it too far though and have
| literally only these four categories on their docs page, which
| never works well imo.
|
| Are you seeing experienced people cargo-culting or simply
| beginners to the framework being religious in its application?
|
| I distinguish the two because I find that, when there's no
| other expert, a beginner is better off being dogmatic than
| trying to "do the right thing." By definition, a beginner does
| _not have the expertise to make this decision_. As you gain
| experience, you 'll start to see where you need to deviate from
| the established rules.
|
| Think of it like home-cooking to a recipe book vs being a
| professional chef throwing things in a pot to feel and taste.
| gnatolf wrote:
| How is this related to https://docs.divio.com/documentation-
| system/ ? Looks incredibly identical.
| zahlman wrote:
| This was discussed in the thread a couple days ago about board
| game rulebook design. I had a similar question
| (https://news.ycombinator.com/item?id=42302038 - although I
| phrased it more like wondering if Procida had been ripped off)
| and got some insightful replies.
|
| In short: it looks identical because it's substantially his
| work, that he did while employed there. In fact, he's the one
| giving the talk in the PyCon Australia video there.
| gnatolf wrote:
| Thank you.
| wadefletch wrote:
| Same guy
| DanieleProcida wrote:
| Explained in https://diataxis.fr/colophon/#origins-and-
| development. No malfeasance! But I wish Divio would take that
| down, it's past its sell-by date now, and I think I got quite a
| few things in it wrong.
| WillAdams wrote:
| I actually find the contrasting approaches (see discussion
| elsethread about the terminology used in the diagram) helpful
| and it's always good to have historical context.
|
| I agree that the Divio site would be well-served by directing
| folks to/acknowledging the newer site (as the newer site
| does).
| Nathanba wrote:
| I don't agree with it because while I think that it's
| theoretically correct, the words are too close together. To me
| "tutorial", "how to guide" and "explanation" are all practically
| synonyms. I know that when you think deeply about it, there are
| legitimate reasons for each category but it's just too close
| semantically that my brain can't see the difference. If I want to
| know how something works and I see "tutorial" and "how to guide"
| I have no idea what to click and I just click on the first thing.
| hebocon wrote:
| Are they really so close?
|
| The lecture is the explanation. The tutorial/lab is a guided
| experience (Microsoft's fake Contoso company comes to mind). A
| how-to guide is what you need when you want to search/chatgpt a
| solution. Reference material: thesaurus, encyclopedia, owner's
| manual.
|
| Video games have built-in tutorials and yet walkthrough guides
| are still necessary for tricky puzzles. You check the key
| bindings as reference.
| Nathanba wrote:
| Your videogame example shows the problem. Tutorials are
| effectively just a different form of walkthrough. You are
| getting walked through the basics. So that's my point, you
| can't have different words on your website that is supposed
| to help people gain understanding and then start off by
| confusing everyone with words that are all so close in
| meaning.
| skydhash wrote:
| The purpose is always the same: To learn. It's how you
| learn and what your learn for that are different. A
| tutorial is for getting exposed to something. A guide is
| for a very specific purpose in something you're already
| familiar with. An explanation is for a deeper understanding
| and references are for not relying on memory. They all
| refer to different things that ultimately falls under the
| same concept (and intersect with each other). If you're
| building a system, you should have all of them otherwise,
| the documentation is lacking.
| hebocon wrote:
| > "tutorials are just a different form of walkthrough"
|
| Yes, one is focused on understanding (mechanics, lore, UI)
| and the other is focused on a specific task (do these steps
| to progress).
|
| Diataxis is not inventing these words - it is using them
| deliberately. You seem unwilling to actually [learn what
| they mean](https://chatgpt.com/share/6751d9b7-3fd4-800a-8b8
| 1-1949069007...).
| ulbu wrote:
| how-to is for configurations. tutorial is for orientation.
| explanation is for models.
| cmehdy wrote:
| It all seems close because the terms are muddied in our minds
| by countless poor instructions over the years.
|
| Their doc actually explains the difference efficiently though :
|
| Tutorials - learning-oriented experiences
|
| How-to guides - goal-oriented directions
|
| Reference - information-oriented technical description
|
| Explanation - understanding-oriented discussion
| Nathanba wrote:
| But I want to learn something in all of those examples. I
| have a goal in all I do. I need technical information in all
| as well and I want to gain understanding in all of those as
| well. It really is just a bad way to name these categories. I
| haven't thought about how to do it better yet, I personally
| like the ziglang docs where everything is presented as a huge
| reference document with examples in each section. The only
| additional thing that is needed is usually something like
| APIs and executable code. Of course the reference document
| can also have executable samples like what Stripe does. But
| somehow I think a dedicated section for example code is
| legitimate in addition to a long reference.
| zahlman wrote:
| >the words are too close together. To me "tutorial", "how to
| guide" and "explanation" are all practically synonyms.
|
| If that set of labels doesn't work for you, there are many
| other ways that the Diataxis doc attempts to explain the
| differences. You might find it a useful exercise to seek terms
| that make more sense to you. Or just to try to understand them
| in other ways - e.g. via the action/cognition ("do vs. think")
| and acquisition/application ("at study vs. at work")
| dichotomies.
|
| There's an entire page devoted to distinguishing tutorials from
| how-to guides (https://diataxis.fr/tutorials-how-to/). (Note
| that this is itself classified as "understanding" material; as
| an exercise, you could try to evaluate the writing there to see
| how it maps onto what is described as "explanation", and _doesn
| 't_ map onto how a "tutorial" is supposed to work.)
|
| But to me, one of the simplest distinctions is that a
| "tutorial" is the sort of thing that you _can 't do on Stack
| Overflow_. That's because a tutorial involves following a
| lesson plan that was set by a teacher, who fills in the
| student's unknown unknowns. On Stack Overflow you must ask a
| question; a tutorial is material for someone who _doesn 't yet
| know what to ask_.
|
| There are plenty of extraordinarily popular questions on Stack
| Overflow that ask how to do some simple task. But to work in
| the format, you have to _ask_ , not simply _request help_ (see
| also: https://meta.stackoverflow.com/questions/284236).
| Nathanba wrote:
| Can you see the problem though: If you need a huge page
| dedicated to explaining the difference between how-tos and
| tutorials then it's clearly too confusing and not obvious at
| all. Nobody is going to need a page telling them the
| difference between sample code and documentation. Those two
| words are obvious even though yes, sample code is of course
| also documentation in a sense.
| red_admiral wrote:
| I think they wanted to separate out four different concepts in
| the territory, needed a name for each one, and so picked four
| almost-synonyms for the labels on the map. We can read
| "tutorial" in their system as a technical term rather than its
| everyday meaning, just as "depression" has a particular meaning
| to a psychologist that might not match everyday use.
|
| I guess that's still better than labelling them Type I-IV
| tutorials.
| agile-gift0262 wrote:
| We use it at our organisation and ever since we adopted it, our
| technical documentation is on a whole other level. That, page
| ownership and periodic reviews of each page by one of the page
| owners has made our technical documentation the only successful
| documentation effort that I've seen
| hebocon wrote:
| My experience trying to implement this for internal use in a
| tech-adjacent industry is that "how-to" guides dominate because
| of a company culture of expediency over quality.
|
| With time and care, those can be turned into tutorials and
| explanations. I use Obsidian to embed reference PDFs.
|
| The end result is too hyperlinked for most to understand and the
| all-in-one outdated mega page in OneNote gets passed around
| instead much to my disappointment.
| hambes wrote:
| I think the graphic used by divio[1] ist so much more intuitive.
| But seems Diataxis has more comprehensive documentation on what
| they mean.
|
| 1: https://docs.divio.com/documentation-system/
| DanieleProcida wrote:
| Why do you think the version on the Divio site is better -
| what's more intuitive about it?
| metaphor wrote:
| I can see your attempts to generalize, i.e.
| Acquisition := Most useful when we're studying
| Application := Most useful when we're working Cognition
| := Theoretical knowledge Action := Practical steps
|
| ...but in my mind, the older quadrant labels were immediately
| insightful at a glance.
|
| Glad to learn that you've given your system a discoverable
| name though; for years since that PyCon presentation, I've
| informally recalled it as "the idea by that Django
| documentation guy".
| _kb wrote:
| Not GP but thought of the exact thing when seeing this - look
| at the wording on the axes.
| svat wrote:
| Not the GP, but I agree:
|
| * "Most useful when we're studying" and "Most useful when
| we're working" are clearer (and also more precise!) than
| abstract ("chunking") terms like "Acquisition" and
| "Application".
|
| * Similarly, "Practical steps" and "Theoretical knowledge"
| are clearer than "Action" and "Cognition".
|
| * For that matter, the "-oriented" suffix in "Learning-
| oriented", "Problem-oriented", "Understanding-oriented",
| "Information-oriented" is helpful, compared to the
| "Learning", "Goals", "Understanding", "Information" abstract
| nouns.
|
| What is common to all three sets of differences is that the
| former labels (on the older diagram) actually carry with them
| their semantic category (what kind of difference is being
| described, namely: (1) when useful, (2) what contents, (3)
| what's the orientation), while in the newer diagram
| everything is just abstract nouns. (E.g. "Useful during
| application" and "Useful during acquisition" would still be
| an improvement over just "Application" and "Acquisition",
| though the older labels are even more direct and clear,
| without requiring the reader to engage in psychology to think
| abstractly about terms like acquisition.)
|
| Also (separate complaint), whenever I want to tell anyone
| else about this "four kinds of documentation" approach, I
| always link to the archived https://web.archive.org/web/20200
| 312220117/https://www.divio... which is the latest version
| that is entirely on a single page. Both the current version
| on the Divio site and on the Diataxis site seem "overdone"; a
| prospective reader has to click on "next" several times and
| it's unlikely they're going to do that.
| DanieleProcida wrote:
| > Also (separate complaint), whenever I want to tell anyone
| else about this "four kinds of documentation" approach, I
| always link to the archived https://web.archive.org/web/202
| 00312220117/https://www.divio... which is the latest
| version that is entirely on a single page.
|
| That's a mistake in my opinion. The big compass of four
| kinds of documentation I eye-catching and memorable, and I
| am sure it is part of the success of Diataxis.
|
| But what gets me out of trouble in my own work every time
| is https://diataxis.fr/compass/. It's one thing to have the
| general idea; it's another to be armed with an effective
| tool to apply to work.
|
| The site doesn't just contain opinions and ideas, it also
| contains tools, that really are worth using.
| svat wrote:
| It's the same "useful when we're learning" vs "useful
| when we're working" dichotomy, isn't it? :) When I want
| to tell someone about the idea of organizing their
| documentation into four buckets -- or really, just about
| being conscious about the goals / the intended audience
| and usage -- I really just want to plant a seed to have
| them open to the idea, i.e. at this point it's
| "Theoretical knowledge" rather than "Practical steps".
| Later if they are persuaded they can go to diataxis.fr
| and learn more / get the "useful when we're working" /
| "application" tools.
|
| [Maybe diataxis.fr itself should be more clearly
| organized into an overview page ("explanation"), and
| separate sections for How-to guides and Reference. Right
| now it has an "Applying Diataxis" and "Understanding
| Diataxis" with a suggestion to start at the former, when
| in fact what I like most about documentation organized
| per the philosophy is that I as a reader can choose to
| start at the "Understanding" pages, instead of reading
| through tutorials and how-to guides and reference pages
| when I have not yet chosen to adopt whatever is being
| documented.]
| cais wrote:
| https://diataxis.fr/colophon/#origins-and-development
|
| I would say the author's Divio re-write at Diataxis.fr is less
| cluttered in its graphic but still essentially the same as the
| one that was used at Divio. I've always viewed the two
| references, for all intent and purpose, the same document for
| the ideas being presented in the context of their specific
| websites.
| piterrro wrote:
| I'm a big fan of Diataxis and I'm using it to build documentation
| for Logdy: https://logdy.dev/docs/quick-start I'm curious how
| people see it and whether it's a useful way to document a
| software product, feel free to leave a comment. So far it proved
| to be an effective way to communicate how to use the product also
| through a series of blog posts that present common use cases.
| Defininitely recommend!
| Vosporos wrote:
| The Haskell language's documentation team officially recommends
| using it: https://blog.haskell.org/documentation-best-practices-
| in-202...
| pivic wrote:
| I'm a technical writer. Diataxis is similar to DITA:
| https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/infor...
|
| On the other hand, systems like these might miss out on what
| users actually need. Diataxis might work for a long time if
| technical documentation is only used in a documentation platform.
| However, if the same information could and should be used in more
| than one place--for example, in a UI, in a documentation portal,
| and in a mobile app--there might be need to break up information
| into smaller pieces in order to assemble them in different ways.
| This is known as 'content reuse', the practice of using the same
| content in multiple places. One approach on how to create and
| edit information for content reuse is described in the 'every
| page is page one' concept: https://everypageispageone.com/the-
| book/
|
| If there's resources and time, I always recommend to do UX
| research at the very start of a project so that one doesn't later
| feel choked by a severely restricted information model.
| Nielsen/Norman have done a lot of research in this area and have
| interesting propositions on how to resolve issues around all of
| this, for example: https://www.nngroup.com/articles/information-
| foraging/#toc-w...
| euroderf wrote:
| Got an opinion on LwDITA ? Or are you deep enough into DITA
| that the complexity is not an issue ?
|
| FWIW if you break up your content into reusable chunks and mark
| it up (with DITA or Docbook semantics, say), it should be a lot
| more amenable to being "understood" by a LLM... but I have not
| seen any data on this.
| robotomir wrote:
| >Diataxis is similar to DITA
|
| I don't see it. DITA differentiates between topic types such as
| task, reference, concept, etc., but a tutorial or a solution
| guide will be a combination of those topic types. Here I
| believe the focus is on deliverables that are larger than the
| individual topic.
| InDubioProRubio wrote:
| So does it track the users-role and reading path + searches?
| Like, if you searched for topic "XY" hop on rail XYZ other user
| with similar role hoped on.
| bjackman wrote:
| As a non writer I found that even without the details there's
| just one very important and very basic insight here:
|
| You don't have to say everything exactly once.
|
| Until being exposed to this idea I always tied myself in knots
| trying to write one stream of text that serves as THE DOCS. It's
| impossible to do this well (once you know, it seems very obvious
| haha). Just realising that you can write the same info in
| different ways for different readers is very helpful!
| smeej wrote:
| Then the challenge becomes recording where each thing is
| recorded so that when it needs to be updated, you update it
| everywhere and don't end up with conflicting documentation.
| 7bit wrote:
| This. Repeating information is helpful. repeated information
| that became inaccurate isn't. It's a difficult line to
| balance
| fmbb wrote:
| Someone will trip on the mistake and report the bug and you
| fix it.
| tjoff wrote:
| You dont get a compile error if the documentation is
| wrong. Chances are you wont notice.
|
| And even if it eventually is fixed it is not obvious that
| the reason for the bug was that the documentation was
| wrong in one particular place.
| elcritch wrote:
| I have a friend who's a pastor. As a basic rule of a good
| sermon he always quoted the old addage: "Tell them what you're
| going to tell them, tell them and tell them what you've told
| them".
| tgv wrote:
| There's more art to it, because there's also an off-putting
| way of doing that, which frequently shows up in
| presentations: you're greeted with a powerpoint slide with
| the topics in bullet points, which the presenter reads out
| loud, then come the slides with each of those points, also
| read out loud, and at the end there's a summary that almost
| copies the first slides, and which --for good measure-- is
| also read out loud. That makes me want to forget everything
| that's been told.
| danparsonson wrote:
| It's an incredibly common mistake, for the presenter to put
| up slide after slide that is just a script of what they
| want to say - then your brain has to choose between
| listening or reading, to the detriment of both.
|
| I have more sympathy with intro and outro summaries, as
| long as the bullet points are short and delivered one at a
| time while the speaker expands upon each one.
|
| Slides should be a visual aid, not a substitute for
| presentation.
| ninalanyon wrote:
| The best presentation I ever saw was done by a colleague
| of Mikel Harry's at a Six Sigma conference in Frankfurt.
| The presenter had no ready made slides but he had an
| overhead projector, three transparencies, a handful of
| dry marker pens, and an eraser. As he spoke he sketched
| charts and diagrams to illustrate his points. If an
| audience member asked a question he was able to provide
| an answer in both words and with another sketch.
| HPsquared wrote:
| The old ways are the best.
| hamdouni wrote:
| Reminds me of Presentation Zen or the 10/20/30 rule which
| states that "a presentation should have ten slides, last
| no more than twenty minutes, and contain no font smaller
| than thirty points."
| ocimbote wrote:
| The anecdote doesn't strike me because your friend the pastor
| said it, but because it's a rule as old as times that every
| high-schooler was taught.
|
| - The introduction should announce the thesis and its
| development - walk your way towards your thesis - The
| conclusion should summarize your thesis (and hint at openings
| towards new grounds)
|
| But somehow, everyone seems to forget it and is in awe
| whenever someone recaps it.
| groby_b wrote:
| And every high schooler, TedX speaker, and Malcom Gladwell
| impersonator gets this wrong: It only works if intro and
| conclusion present a different view on the information,
| otherwise it's simply boring the audience to death.
| samuell wrote:
| There is even a lot of potential for communicating more
| effectively here:
|
| By giving 2-3 examples, that describe the same thing from
| slightly different aspects, you can to some extent overcome the
| ambiguities of language, by letting the reader figure out the
| common denominator between those examples, which will be a lot
| less ambiguous that only telling it from one example.
|
| Let me give you two examples more [...] ;)
|
| (Related, this is a technique used extensively by writers like
| king Solomon in the book of Proverbs in the Bible.)
| BlueTemplar wrote:
| And two of them should be the most obvious example you can
| think of, and the weirdest example you can think of.
| hitekker wrote:
| Giving a few good examples also has the benefit of
| demonstrating the author's own understanding. If the author
| can't describe the matter in different ways, it shows don't
| have a feel for "it", and they're not grasping it rightly or
| even touching it at all. I've found that audiences can sense
| when a speaker is out-of-touch, and will politely ignore
| them.
|
| Separately, I've heard that the Nicene Creed and its
| ancillaries had the repetitions hardcoded to forestall
| natural schism/emergent mutations in the generational belief
| system.
| bbminner wrote:
| True, even when you are writing a scientific publication with a
| hard page limits (~8 pages), it is advisable to reiterate the
| core messages multiple times as you add more context and
| details:
|
| = abstract 1) in this paper we show that X holds by evaluating
| Y against Z = intro 2) the problem of A is important because B,
| however the X aspect was overlooked; we show that evaluating Y
| highlights real world challenges, in contrast to Z, that... 3)
| to sum up, we found that Y is better at Z because X = related
| work Z approached the problem as..., which improved..., but as
| we show further, this is not sufficient to achieve...
|
| .. and so on - you circle around the main message over and over
| again in each section.
| ysofunny wrote:
| expanding this take perhaps too much
|
| ...even the source code itself "says", in its own way, the same
| thing as the documentation, just to a different "audience" (the
| compilers)
| swyx wrote:
| here is my alternative system: https://www.swyx.io/documentation-
| levels
|
| i find that the divio/diataxis 2x2 can be -too- complete, which
| is harmful for earlier stage, less mature open source projects,
| and also equal weights areas that nobody equal weights in real
| life.
|
| my system takes inspiration from real docs and creates a
| progression based on project maturity, aka prioritizing just the
| important stuff at the early stages.
|
| - *Level 0: Basic proof of concept* - _Example
| audience: you/colleagues/hobbyists_ - One sentence
| description for github headline - README with API docs
| - goal is to save yourself from looking at source code
|
| - *Level 1: v0.x* - _Example audience: greenfield
| early adopters. Ok with missing documentation, they are here for
| the idea. can contribute code/docs_ - One paragraph
| description with more context - could be a sales pitch but also
| give an idea of when to use you - Feature list/Project
| Goals - Install + Config Instructions
|
| - *Level 2: v1* - _Example audience: brownfield
| early adopters. Ok with bugs, they have some problem that isnt
| well addressed. Needs convincing._ - Comparison vs
| comparable libraries - Problem Statement - what you
| solve, how the developer/end user is better off with your thing
| than handwritten. aka Why You Exist - Basic Examples
| - Live Demos
|
| - *Level 3: vX* - _Example audience: early
| majority user. Wants ease of use, quick wins. Need to be very
| reliable. Needs content to sell solution to team_ -
| Project Status badges - Tutorial - Third
| Party Plugins/Libraries - How-To
| Guide/Cookbook/Recipes - User/Maintainer Content
| - Official Blog/Project and Meeting Notes - Talks
| - 3rd Party Blogs - Video Tutorials - Podcasts
| - Comprehensive Examples
|
| - *Level 4: Production use for multiple years* -
| _Example audience: expert user. Needs API stability/migration
| instructions, deep insight on how the project works and how it
| can solve problems. Needs to customize/adapt for at-scale/weird
| usecases_ - Growing the MetaLanguage -
| Origin Story/Naming - Who Uses Us - Logos
| - Quotes/endorsements/testimonials - Link to production
| use - Funding - Migration docs from
| previous versions - Roadmap - Reader-
| friendly Changelog - Anti-Docs - Helping
| Contributors - _Example audience: Industry beginner.
| They may not know any alternatives. You are the entire world to
| them._ - Explain acronyms, jargon - "1 to
| N" Docs - Different docs for different audiences (eg
| JS/Android/iOS) - Different languages -
| Examples - [Vue](https://vuejs.org/) -
| [Django](https://docs.djangoproject.com/en/3.0/) - some [meta
| thoughts here](https://jacobian.org/2009/nov/10/what-to-write/)
| - [React](https://reactjs.org)
| 47 wrote:
| Diataxis is a great way to structure documentation, but I think
| its real value is in simplifying how we think about writing docs.
|
| It shifts the focus from trying to cram everything into one
| 'perfect document' to recognizing that different users have
| different needs.
|
| Like, tutorials are for learning by doing, guides are for solving
| specific problems, reference is for quick lookups, and
| explanations dive into the 'why.'
|
| That clarity alone can make one write useful docs.
|
| That being said, sticking too rigidly to any system can be a
| trap.
| 3abiton wrote:
| Isn't the documentation task highly dependent on the goal and
| prospective users. Or is there a unified paradigm?
| djaychela wrote:
| I like the idea of this (and have been lucky enough to meet the
| creator a couple of times at PyconUK - he's a talented and very
| friendly chap), but I have a reservation about being this rigid
| about differentiating between the various areas of documentation
| in this way.
|
| During a sprint I was told that the docs I was preparing (not by
| Daniele, for the record) were mixing modalities and not
| acceptable because of this. Not pulling rank, but I've been a
| teacher for 20+ years, and I have a reasonable ida of how to
| explain things and how to scaffold learning so that people can
| both get things done and progress with understanding happening as
| part of that.
|
| As long as there's not total rigidity then this is a great tool
| for deciding how to produce documentation and what each type of
| document should do. I often see examples in documentation (numpy
| springs to mind) where the examples could be a lot better chosen
| rather than 'magic from the sky'. A good, well chosen example can
| provide a lot of learning while illustrating usage, a corner case
| or other things to be aware of.
| flowingfocus wrote:
| I recently built a small, free analysis tool that takes public
| documentation git repos and evaluates the content against this
| framework:
|
| https://app.getdocsy.com/analysis/
| chris_nielsen wrote:
| Where would ChatGPT fit?
| red_admiral wrote:
| It can, on a good day, produce several kinds of documentation
| if you describe what you want.
| chris_nielsen wrote:
| Yeah LLMs ingest all 4 and can conversationally give you all
| 4. I suppose it's orthogonal.
| asymmetric wrote:
| Does anyone have examples of OSS projects using this framework,
| and having good documentation?
|
| I find the framework doesn't really speak to me (as a user, or
| prospective docs writer), and IME trying it out in communities
| I'm a part of, it didn't particularly improve the situation, as I
| had perhaps naively expected.
| f3408fh wrote:
| All of Canonical's documentation is written with Diataxis. Here
| are the Ubuntu Server docs: https://ubuntu.com/server/docs
| losvedir wrote:
| Ooooh! I've seen this organization before, but didn't realize it
| was a thing, or had a name. I don't personally like it, as I get
| confused about where to go. When I saw "tutorials" and "how-to
| guides", for example, I had thought those were roughly the same
| thing and didn't know which to click. And seeing "Explanation"
| separately was even worse because why would I want a guide or
| tutorial without explanations??
|
| I get "reference" as a separate section, maybe, though to my mind
| the best docs are built around reference with explanations and
| little code samples and how-tos mixed in as necessary, and maybe
| a single "Getting Started" guide for installation and
| configuration and stuff like that.
| ChrisMarshallNY wrote:
| Having just completed my first (and last, for a while) shipping
| SwiftUI app, I _very much_ think that documentation has been
| treated in shabby fashion, in the modern tech scene. I sorely
| miss the work done by all those great tech writers that Apple
| fired. Their engineers are _terrible_ documenters.
|
| I'm always a bit leery of "dogmatic" approaches, though, because
| they tend to develop a "priesthood," that refuses to bend; even
| when reality demands it.
|
| In my experience, the initial developers of the dogma use it to
| marvelous effect, but subsequent "priests" screw the pooch;
| sometimes, turning the approach into a curse. Many good ideas
| have been destroyed by too-rigid applications (What is "Agile"?).
|
| I see any documentation as having basically two faces: The
| maintainer, and the user. Each, has drastically different needs,
| and should probably be addressed by completely different teams.
|
| As has been alluded to, in other comments, you can have issues
| with multiple instances of documentation, falling out of sync
| (the curse of most wiki-style documentation), but results matter.
| If the multiple instances can be effectively synced, then the
| documentation is effective and useful to its consumers. If no one
| reads the perfectly formatted and synced documentation, it's
| worthless.
|
| On SNL, Phil Hartman _[n]_ used to play The Anal-Retentive Chef.
| In one skit, he spent so much time prepping, that he couldn 't
| actually demonstrate the recipe.
|
| I see a lot of that, in tech. Toolchains and libraries that are
| absolutely perfect, but are unusable, in practice.
|
| Documentation is an amalgam of many disciplines; human
| nature/psychology, graphic design, information architecture,
| technical infrastructure, publishing and distribution, etc.
|
| I really think it's often treated as an afterthought, in most
| projects, and I believe that it should be a first-class
| consideration, at the Requirements stage, onwards.
| ebiester wrote:
| I don't think of diataxis as a dogmatic approach, but rather a
| pragmatic one. You can dive pretty deep into the weeds in how
| to structure your documentation, but this is a very good
| training wheels until you find places that leak.
| ChrisMarshallNY wrote:
| I agree, but I guarantee that it will become dogma.
|
| I strongly suspect that few of the originators of dogma
| considered their work as such.
|
| As I have gotten older, I have learned that "It Depends" is
| the only true dogma for almost all aspects of my life.
| dizzant wrote:
| > Many good ideas have been destroyed by too-rigid applications
|
| This is an interesting perspective that I disagree with. You
| seem to be saying that a general misunderstanding or
| misapplication of a good idea degrades the idea to a point that
| "destroys" it.
|
| On the contrary, I believe there is experience to be gained in
| practice: either the initial idea wasn't good after all, in
| which case we're destroying an illusion; or the poor examples
| serve to refine the idea by clarifying some ambiguity that,
| interpreted wrongly, leads to failure.
|
| Perhaps your argument is that many people may become familiar
| with the bad implementations and the idea's popularity will
| decline, depressing demand for refined implementations. This is
| likely true, but reflects the tragedy of the anticommons, not a
| degradation in the idea itself.
| ChrisMarshallNY wrote:
| Well, what I mean, is that folks invest in the dogma, to the
| point where they refuse to accept any changes to fit
| realities, and often believe that they can apply the dogma,
| in areas, or in a manner, where it is not appropriate.
|
| There's an old Swiss Army saying _" When the map and the
| terrain disagree, believe the terrain."_.
|
| People who invest in dogma, refuse to look at the terrain.
| The map is The Only Source of Truth.
|
| I believe that most dogma comes from something that works in
| one or more contexts, and may actually be highly effective,
| in other contexts, _as long as it is adjusted for context_.
| That last part, is what kills it. People refuse to change,
| and the dogma gets a bad name as a "failure."
|
| You see this constantly.
| dsmmcken wrote:
| I feel like I should be writing with the goal that the end reader
| is actually an LLM. The LLM will be the one spitting out the
| answers to the actual users via things like co-pilot, but I am
| not sure how that should change my approach to structure or level
| of detail in docs. Heavier on the number of code examples?
| pault wrote:
| Ask an LLM to write it?
| Mathnerd314 wrote:
| Well, look at the process of training a chatbot:
|
| - first you make a "raw" corpus, with all the information
| needed to produce an answer
|
| - then you generate sample question-answer pairs
|
| - then you use AI to make better questions and better answers
| (look at e.g. WizardLM https://arxiv.org/pdf/2304.12244)
|
| - can also finetune with RLHF or modify the Q-A pairs directly
|
| - then you have a final model finetune once the Q-A pairs look
| good
|
| - then you use RAG over the corpus and the Q-A pairs because
| the model doesn't remember all the facts
|
| - then you have a bullshit detector to avoid hallucinations
|
| So the corpus is very important, and the Q-A pairs are also
| important. I would say you've got to make the corpus by hand,
| or by very specific LLM prompts. And meanwhile you should be
| developing the Q-A pairs with LLMs as the project develops -
| this gives a good indication of what the LLM knows, what needs
| work, etc. When you have a good set of Q-A pairs you could
| probably publish it as a static website, save money on LLM
| generation costs if people don't need super-specific answers.
|
| To add to the current top-scoring comment, though
| (https://news.ycombinator.com/item?id=42326324), one advantage
| of an LLM-based workflow is that the corpus is the single
| source of truth. It is true that good documentation repeats
| itself, but from a maintenance standpoint, changing all the
| occurrences of a fact, idea, etc. is hard work, whereas
| changing it once in the corpus and then regenerating all the QA
| pairs is straightforward.
| _acco wrote:
| We _just_ applied this framework to the Sequin [1] docs two weeks
| ago. It has felt _so nice_ to have a framework. I think our docs
| flow really well now, and it 's been easier for us to add and
| maintain docs because we know where to put things.
|
| The slightly ironic part is that the Diataxis docs themselves are
| a bit obtuse. It's a little verbose. So it took a couple passes
| for it all to click.
|
| The analogy I gave my team that was helpful for everyone's
| understanding:
|
| Imagine you're shopping for a piece of cooking equipment, like a
| pressure cooker.
|
| The first thing you're going to look at is the "quickstart"
| (tutorial) - how does this thing work _generally_? You just want
| to see it go from A to B.
|
| Then, you're going to wonder how to use it to cook a particular
| dish you like. That's a how-to.
|
| If you're really curious about anything you've seen so far,
| _then_ you 'll flip to the reference to read more about it. For
| example, you might check the exact minutes needed for different
| types of beans.
|
| And finally, when you're really invested in pressure cooking and
| want to understand the science behind it - why pressure affects
| cooking times, how the safety mechanisms work, etc. - that's when
| you'll read the explanatory content.
|
| Comically, our docs were completely backwards: we _lead_ with
| explanation ( "How Sequin Works"). I think that's the natural
| impulse of an engineer: let me tell you how this thing works and
| why we built it this way so you can develop a mental model. Then
| you'll surely get it, right?
|
| While that may be technically accurate, a person doesn't have the
| time or patience for that. You need to ramp them into your world.
| The quickstart -> how-to -> reference flow is a great way to do
| that. Then if you really have their attention, you can galvanize
| them about your approach with explanatory material.
|
| [1] https://sequinstream.com/docs
|
| PS: If you have any feedback on our docs, lmk :)
| mopierotti wrote:
| I checked out your docs, and I agree that they flow very
| nicely! So often it seems that docs are either frustratingly
| vague to the point where it almost seems like the company is
| embarrassed to admit that their tool is a tool and not a
| "transformative synergy experience" (or similar nonsense), or
| docs immediately get overly specific without covering "why this
| product exists".
|
| Minor note: The only thing in your docs that made me pause was
| the repeated use of "CDC", which I had to google the definition
| of. (For context, I have implemented "CDC" several times in my
| career, but wasn't familiar with the acronym)
| _acco wrote:
| Aye, thanks! That's very helpful to hear. I just cut back our
| use of the acronym a ton:
|
| https://github.com/sequinstream/sequin/commit/28bfba603da6d2.
| ..
| mdaniel wrote:
| In case you weren't already aware, most markdown parsers
| support actual HTML tags in it, and there's <abbr
| title="change data capture">CDC</abbr> that allows being
| visually succinct, is a11y friendly, and in most browsers
| is visually distinct to prompt the user there's more
| content hidden in the hover or long-press
|
| https://developer.mozilla.org/en-
| US/docs/Web/HTML/Element/ab...
|
| I'm also aware of https://developer.mozilla.org/en-
| US/docs/Web/HTML/Element/df... but I think it has more
| nuance to it and for sure involves having a lot more
| supporting structure in the document
| _acco wrote:
| Very fun - I wasn't aware, thank you!
| eightnoneone wrote:
| You were _this_ close!
|
| What's a CDC?
| eightnoneone wrote:
| I think having those four approaches is the key thing and
| you're addressing it well. The flow is really the readers
| choice. My brain works in the way of wanting the overall
| explanation first. Then I seek the how-tos and tutorials.
| mtrovo wrote:
| This analogy is really good, now I totally see the benefit of
| this framework.
| FigurativeVoid wrote:
| We have been implementing Diataxis style engineering
| documentation. We have "librarians" that make sure information is
| going to the place, and that we aren't creating unnecessary
| duplication.
| GarnetFloride wrote:
| As a technical writer, I had been groping my way toward a
| framework like this myself and this is great. It is great because
| it gives a simple framework to work with that most people can
| understand very quickly and the graphic is amazing for
| referencing.
|
| I explain it in a more audience focused way:
|
| An explanation is for a prospective customer.
|
| A tutorial is for someone who's never used it before.
|
| A how-to is for someone familiar with it but doesn't use that
| particular feature often enough to memorize it.
|
| A reference is for people wanting to become an experts on the
| product.
| Attummm wrote:
| The ideas presented are great, and I can see myself adopting them
| in the future. However, the tone of the accompanying text feels
| off-putting, which makes me hesitant to share it. I hope this
| aspect improves over time
| postoplust wrote:
| I use and highly recommend this framework as the starting point
| for any technical documentation. It helped me learn how to keep
| the detailed technical explanations out of the how-to documents.
| Before I learned of Diataxis, my how-to docs were much longer and
| hard to follow when things go right (because I had lots of, "if
| this doesn't work, investigate A, B, C...").
| elijahbenizzy wrote:
| We've leveraged Diataxis heavily for Hamilton and Burr
| documentation:
|
| - https://hamilton.dagworks.io
|
| - https://burr.dagworks.io
|
| It's not always the easiest to follow (we often have
| disagreements about whether something is a tutorial or a how-to),
| but it's a really valuable framing and I think our docs have
| gotten better because of it.
| hermitcrab wrote:
| I arrived at a similar approach for my product documentation,
| with main sections:
|
| -Tutorial/Quick start
|
| -Reference (topic based)
|
| -How-to guides (task based)
|
| With an extra section:
|
| -Expert tips (various things the product can do that aren't
| obvious or easy to discover)
|
| It does mean that there is a certain amount of repetition between
| sections, but I don't think that is a big problem. You just have
| to be conscientious when updating things.
|
| In my experience, the key thing about documentation is to write
| it as you are creating the product. Do not leave it all unti the
| end!
___________________________________________________________________
(page generated 2024-12-05 23:00 UTC)