9 ms·
Diátaxis – A systematic approach to technical documentation authoring
- n3storm 2y ago[flagged]
- deleted 2y ago[deleted]
- gavindean90 2y agoI’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 2y agoI 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 2y agoYup, 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 2y agoA 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 2y agoWhat third dimension would you add?
- haydenchambers 2y ago[dead]
- euroderf 2y agoFair question. I've read a couple of critiques of Diátaxis 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 Diátaxis.
- DanieleProcida 2y agoFAQ 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 2y agoDepth? 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 2y agoand I'll upvote it every time it comes up.
- perlgeek 2y agoA natural third dimension is language. If your user base is very international, you might need most of these documents in multiple languages.
- euroderf 2y agoUser interface language is orthogonal to ebberyting.
- remram 2y agoFor every dimension you add, you double the amount of docs you have to write.
- euroderf 2y agoYou double the number of document types. But if it helps, it helps.
- pastage 2y agoI 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-canonical-documentation https://ubuntu.com/blog/diataxis-a-new-foundation-for-canoni...
- DanieleProcida 2y agoExamples in reference material are an excellent idea, and not at all in contradiction to the principles of Diátaxis. 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 2y agoGolang 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 2y agoIt'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 2y agoEh, 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 2y agoThe 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 2y agoI 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 2y ago
- gnatolf 2y agoHow is this related to https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/ ? Looks incredibly identical.
- zahlman 2y agoThis 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 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 2y agoThank you.
- wadefletch 2y agoSame guy
- DanieleProcida 2y agoExplained in https://diataxis.fr/colophon/#origins-and-development 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 2y agoI 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 2y agoI 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.
- strongbond 2y agoYou also need good writers who by example make it perfectly clear what's what.
- zenoprax 2y agoAre 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 2y agoYour 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 2y agoThe 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.
- agile-gift0262 2y agoWe 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
- zenoprax 2y agoMy 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 2y agoI think the graphic used by divio[1] ist so much more intuitive. But seems Diátaxis has more comprehensive documentation on what they mean. 1: https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/
- DanieleProcida 2y agoWhy do you think the version on the Divio site is better - what's more intuitive about it?
- metaphor 2y agoI 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 2y agoNot GP but thought of the exact thing when seeing this - look at the wording on the axes.
- svat 2y agoNot 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/20200312220117/https://www.divio.com/blog/documentation/ https://web.archive.org/web/20200312220117/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.
- piterrro 2y agoI'm a big fan of Diátaxis and I'm using it to build documentation for Logdy: https://logdy.dev/docs/quick-start 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!
- strongbond 2y agoI don't know if it's perfect, but I have yet to meet anything better. I discovered it late in my 20-year technical writing career, and it felt like meeting an old friend for the first time.
- Vosporos 2y agoThe Haskell language's documentation team officially recommends using it: https://blog.haskell.org/documentation-best-practices-in-2024/ https://blog.haskell.org/documentation-best-practices-in-202...
- pivic 2y agoI'm a technical writer. Diátaxis is similar to DITA: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html 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. Diátaxis 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/ 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-what-is-information-foraging-2 https://www.nngroup.com/articles/information-foraging/#toc-w...
- strongbond 2y agoThe trouble with DITA is that it is very often accompanied by its own very opinionated toolchain, although of course it's not mandatory. There are better ways to write docs nowadays than wrestle with XSL/FO and its brethren.
- euroderf 2y agoGot 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 2y ago>Diátaxis 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 2y agoSo 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 2y agoAs 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 2y agoThen 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 2y agoThis. Repeating information is helpful. repeated information that became inaccurate isn't. It's a difficult line to balance
- fmbb 2y agoSomeone will trip on the mistake and report the bug and you fix it.
- deleted 2y ago[deleted]
- tjoff 2y agoYou 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.
- smeej 2y agoAnd by then you have several people on the team who have thought the wrong way is the right way for months, never mind your support team probably giving end users bad information. It's messy.
- swyx 2y agohere is my alternative system: https://www.swyx.io/documentation-levels 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 2y agoDiátaxis 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 2y agoIsn't the documentation task highly dependent on the goal and prospective users. Or is there a unified paradigm?
- djaychela 2y agoI 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 2y agoI 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/ https://app.getdocsy.com/analysis/
- chris_nielsen 2y agoWhere would ChatGPT fit?
- red_admiral 2y agoIt can, on a good day, produce several kinds of documentation if you describe what you want.
- chris_nielsen 2y agoYeah LLMs ingest all 4 and can conversationally give you all 4. I suppose it’s orthogonal.
- asymmetric 2y agoDoes 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 2y agoAll of Canonical's documentation is written with Diataxis. Here are the Ubuntu Server docs: https://ubuntu.com/server/docs https://ubuntu.com/server/docs
- losvedir 2y agoOoooh! 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 2y agoHaving 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 2y agoI 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 2y agoI 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.
- dsmmcken 2y agoI 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 2y agoAsk an LLM to write it?
- Mathnerd314 2y agoWell, 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 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 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 2y agoWe 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 https://sequinstream.com/docs PS: If you have any feedback on our docs, lmk :)
- mopierotti 2y agoI 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)
- FigurativeVoid 2y agoWe have been implementing Diátaxis style engineering documentation. We have "librarians" that make sure information is going to the place, and that we aren't creating unnecessary duplication.
- GarnetFloride 2y agoAs 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.
- deleted 2y ago[deleted]
- Attummm 2y agoThe 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 2y agoI 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 2y agoWe've leveraged Diataxis heavily for Hamilton and Burr documentation: - https://hamilton.dagworks.io https://hamilton.dagworks.io - https://burr.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 2y agoI 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!