6 ms·

My Problem with the Four-Document Model

204 points by zdw 3y ago

apodolny 3y ago
Glad someone has written about this! We talk about the Diátaxis model a lot at Scribe (scribehow.com) where we feel like the how-to guide gets very little love from most of the traditional documentation platforms, which feel like they were all designed for reference material and not much else.
swyx 3y ago
I am also interested in alternatives to the 4 document model, having struggled with implementing/maintaining it with limited resources at 3 startups now. https://www.swyx.io/documentation-levels https://www.swyx.io/documentation-levels is my proposal. match documentation features to project maturity. 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 and so on (up to level 6 in the doc)
- riwsky 3y ago
  Know your audience, know your audience, know your audience.
ftxbro 3y ago
there are only four audiences so there can be only four document types
fsckboy 3y ago
I myself prefer the 5th document: Cheatsheet, with variety of not overly simple examples (where i can figure out that if I don't want an option I can leave it out, but now I know the option (TL;DR the other 4 are Tutorial, How-to Guides, Explanation, Reference)
- HWR_14 3y ago
  Snippets was brought up in the article, and seems reasonably equivalent to a cheatsheet.
nobeh 3y ago
Thanks for the interesting post and bringing a critical viewpoint. I am curious to learn about what other common best practices are around?
cratermoon 3y ago
The author previously discussed the four-document model and some additional kinds of documents at <https://buttondown.email/hillelwayne/archive/beyond-the-four-document-model/ https://buttondown.email/hillelwayne/archive/beyond-the-four...>, and goes into further detail about conceptual overviews and examples. Of the other kinds of documents he mentions, "Best Practices" are often the ones I look for early on when learning a new language or library. It's easier for me to get up to speed by emulating what works.
- alexchamberlain 3y ago
  Can we call it "Good Practices" instead, and make sure they qualify when they apply? Practices are rarely the best in all cases, and often change over time.
  - inopinatus 3y ago
    There’s an argument to be made for documenting Worst Practices, too. Along with “Unsupported configurations”, “Practical limitations”, “Unmet use cases”, and “Failure modes”. That kind of information is absolute gold for solution design. Far too often I've found myself trying to discern the true envelope of some subsystem's capabilities by the negative space implied in the product docs, a task sometimes comparable to reading tea leaves. Alas, many product managers regard documentation as propaganda, thus in the interests of fragile egos such topics are commonly omitted.
    - cratermoon 3y ago
      I call the parts of my documents that address limitations and unmet use cases the "Not Gonna Do It" sections. In my case, it's especially important to document functionality that was considered and rejected, and why. Where performance, security, and similar qualities were recommended by programmers but rejected by management, I especially want to record those for later reference in case of problems. Maybe what I write doesn't make it into end-user facing product documentation, but it's on the record. To give an example, at one project I consulted on, all of the user interface text was written in english, with US measurements with no i18n or l10n system. The company I was working with has customers from, if not worldwide, at least all of the western hemisphere. About six months later project management finally came to the realization that they were going to need at the very least multiple languages, and a lot of work was ahead to retrofit.
inopinatus 3y ago
Very well, 6doc it is then.
exmadscientist 3y ago
The article's idea of Conceptual Overviews is something I find myself missing in a lot of projects' documentation. But I'd go even further. That paragraph about soup from the article? Every single piece of top-level documentation for any project anywhere should start with that paragraph. What is it? Who cares or should care? What can it do? When is it a good choice? I spend a lot of time searching, trying to decide if something is worth my time to research more. Writing that paragraph (and it really does need to be just one paragraph; I guess you can split it in two if you must) is very, very valuable to your prospective users! In the hardware world everyone does this: the first page of every datasheet tries to answer these questions. That's done not because it's required, but because it helps sell parts to engineers.
- spondylosaurus 3y ago
  There's a great tech writing book called Every Page is Page One[1] that changed how I write docs. Its primary conceit is basically what you've described: every single doc needs to immediately orient its reader, either with an intro paragraph or seamless hyperlinks to relevant background material (or, ideally, both). If the reader lands on a page that isn't right for them, it's the writer's job to leave a trail of breadcrumbs that leads them where they need to go. To grossly oversimplify, the EPPO page structure is almost like a Wikipedia article. Imagine you end up on the page for, idk, anthrax. If you already know a bit about yucky diseases and want to learn more, you'll read on. If you get a couple paragraphs in and you're like "wait, what exactly is a bacterium?", you can click the hyperlink to the relevant article about bacteria. And if you actually wanted to read about the metal band, there's an escape hatch to redirect you to the correct location. [1] https://everypageispageone.com/ https://everypageispageone.com/
vgivanovic 3y ago
Examples, examples, examples! Just today I failed to find an example of mounting multiple drives as one Btrfs filesystem. Plenty of how to create Btrfs filesystem examples. But how to mount them? Crickets. I eventually figured it out, but at a large cost in time.
- wtallis 3y ago
  I think you just wasted a lot of time looking for complexity that you wrongly expected to exist. When I google "btrfs mount multiple device", two of the top three results include exactly the example you needed to see (and probably skipped over believing it couldn't be that simple), and the other one indirectly explains what's going on by discussing the necessity of a btrfs scan when using multiple devices (and how to construct an fstab entry if your boot process doesn't do a btrfs scan). For the record: to mount a multiple device btrfs filesystem, use an ordinary mount command with any one of the block devices that are part of the file system. Every device contains information about what other devices are supposed to be part of that filesystem. I'm not sure if there are any techniques documentation writers can use to avoid this "hiding in plain sight" kind of problem.
  - planede 3y ago
    > For the record: to mount a multiple device btrfs filesystem, use an ordinary mount command with any one of the block devices that are part of the file system. Every device contains information about what other devices are supposed to be part of that filesystem. If something works "automagically" like this then I jump into thinking about failure modes. Will it mount if one of the other devices are missing or failing? Will it just warn that the raid is degraded and I should add a new device? Will it mount read-only? > I'm not sure if there are any techniques documentation writers can use to avoid this "hiding in plain sight" kind of problem. The problem is probably lack of emphasis. It's guess it's hard to achieve in writing, if a solution is simple than you don't need many words to explain it, then it becomes easy to skip over.
    - wtallis 3y ago
kaycebasques 3y ago
My perspective as a technical writer of ~10 years. > In short, the 4doc model is not universal. It was designed for documenting tools and doesn’t fully address the needs of frameworks and programming languages. I think that the author is onto something here, but I'm not sold on the exact example that the author provides (programming languages). Honest question: are the Python docs deeply loved by the Python community? In other words, should we be holding up the Python docs as an example of great docs and therefore an example that the 4doc model is inadequate? I've done a fair bit of Python programming myself. In my experience the Python docs are decent: not great, not terrible. If we look at the Rust docs, which seem to get much more praise than the Python docs, then the author's argument seems to break down for me a bit. Because the Rust docs seem to be more aligned with the 4doc model than the Python docs, and the Rust docs are more praised than the Python docs. One domain where I recently saw the limitations of the 4doc model is OS bringup. I was writing docs explaining how to get an OS running on new hardware. Customer feedback suggested that the ideal doc would start off as an overview, and then morph into a guide, but the guide section would also need constant small explanations of conceptual stuff. I also agree with the "it's not comprehensive" premise but again the example fell flat for me. Conceptual overviews totally overlap with explanations. I can elaborate if needed but I honestly think the author is imposing a narrow definition of explanations that does not exist in the 4doc model. The main instances where the 4doc model is glaringly incomplete for me are homepages and release notes. You can kinda bucket homepages under explanations or references. And you can kinda bucket release notes under references. But those classifications are a stretch. The fact that practically every technical project needs a homepage and most need release notes really suggests to me that they are their own categories and deserve unique guidelines. The key here would be to go back to goal-focused thinking. My guess for the #1 reason for 4doc's success is how it aligns each doc type with a goal: * Tutorials - Learning * How-To Guides - Tasks * Explanations - Understanding * References - Information If you're going to propose a new universal doc type, you should be able to propose a new universal goal type as well. My argument about release notes begins to fall short here: release notes are totally about information so they should probably just get bucketed cleanly under references. But I think my argument about homepages holds its ground better: * Homepages - Convincing MAYBE (but probably not) we can save release notes like this: * Release Notes - Diffing The Pigweed docs might be an interesting example of where the 4doc model falls short. Here in SEED-0102 (our docs plan) you can see how the 4doc model is the foundation but we felt the need to define further categories of docs. In terms of domains (recall how the author suggested the 4doc is good for tools but not programming languages) Pigweed is a collection of a bunch of stuff for embedded development (libraries, tools, etc.) so that could explain why we needed to define more doc types. https://pigweed.dev/seed/0102-module-docs.html https://pigweed.dev/seed/0102-module-docs.html The topic of examples came up recently on the Write The Docs Slack. Daniele Procida had a very thoughtful response. Original comment from Rob H: > I tend to like to categorize some of my items by whether or not they have "examples," which seems to be an attribute that could apply to multiple diataxis types, but not a standalone type by itself. I could use a tag on these items with the word "examples," but I feel almost like it needs a category by itself, given that it seems to be my learning style. But then there's another twist: in some cases, an "example" is more of an "inspiration for a way to use something," and in others, an "example" is more of a "clarifier that completes the learning process." Response from Procida: > You can and probably should use examples everywhere. I think that a well-crafted example can often illuminate something much better than a painstaking attempt to describe it fully and completely. In every aspect of life in fact. I bet that you can think of someone who was an example to you, of say moral righteousness, that taught and inspired you more than any amount of moral theorising and argument (I certainly can). Examples are very powerful, and we are intelligent, so we use them very well when we encounter them. Examples illustrate extremely effectively, whether they are illustrating how-to guides, explanation, or whatever. But examples on their own seem a bit deracinated. What are they examples of? Don’t they need context?
onion2k 3y ago
The author makes a cogent argument but I can't help thinking they've fallen into a 'perfect is the enemy of good' trap. Sure, 4doc doesn't perfectly describe exactly how you should document everything, but it's better than every other approach I've encountered and that gives it a lot of value to me. It's likely that there isn't a documentation system that works perfectly for everything, especially if you accept an argument of 'this documentation system is a bit too verbose' which would stop you just enumerating everything imaginable. You have to be pragmatic. If your docs could be improved by adopting a 4doc approach then you should, because they'll be better docs for it, even if the system is technically flawed. Similarly, if you have a doc that doesn't fit anywhere in the 4doc system but it's a useful doc, then it's still worth adding. 4doc is a process. It is not perfect, but it's still useful, and you might need to step outside of it occasionally. That's fine.
- brianpan 3y ago
  The last section is titled "Good is the enemy of better".
- sundarurfriend 3y ago
  I don't think you and the author disagree at all. They say > I’m glad that people use it. I’m also a little frustrated that people use it even when its inappropriate. > I’ve read plenty of good 4doc pages. Even so, it still leads to the same kind of “this is the only way” thinking. People use the model even when it’s not the right choice and they don’t vary up the format even when they should. and you say > 4doc is a process. It is not perfect, but it's still useful, and you might need to step outside of it occasionally. --- The specific issue here is that it seems like the author has come across many people who use the 4doc model dogmatically. The article is geared specifically towards them, and is not an attempt to tear down the 4doc model as a whole.
throwawaaarrgh 3y ago
dumb people make grandiose statements and dumb people upvote it (aka the idiocracy model of culture). there will always be dumb popular models. make up your own, use that, move along
BiteCode_dev 3y ago
Yes, the 4 doc model is flawed, but if everybody followed it, we would still get on average 10 times better doc. When that happen, we can worry about improving, but most people are just terrible at explaining things. Also, how to guide are not more and more covered by chatgpt. But I don't think it should be a good reason to stop writing them. For example, I wrote an article on "Parameters, options and flags for Python scripts": https://www.bitecode.dev/p/parameters-options-and-flags-for https://www.bitecode.dev/p/parameters-options-and-flags-for This is typically the type of things you get great ROI with chatgpt. Yet: - it's still faster to copy the summary of the article - you need to understand the output of chatgpt so the article is useful to beginners - you need to be able to use the right words to ask chatgpt what you want, which again, implies you understand the problem - good practices and conventions are contextual, so the doc still helps On the other hand, it's hard to find a lone article on the net, most people will find it faster with chatgpt. But for your particular documentation of your particular product, that's still important to produce it. Because your best users will get familiar about your docs.
mjw1007 3y ago
I think the biggest weakness with the four-document model is that it doesn't have a proper place for rigorous documentation of the system's concepts and model. The biggest problem I find with software documentation is that the only rigorous part is a "Reference" which is organised as a list of functions or configuration options or commands or whatever, and while each individual item looks OK, they don't add up to a full description. One clue that you've got this problem is having reference items which use technical terms which aren't defined, or are only defined in the informal part of the documentation. Another form of this problem is a reference that's heavy on how options modify behaviour but omits any promises about the parts of the behaviour which are unconfigurable. The four-document model's division of "Explanation" and "Reference" doesn't help avoid this problem. The "Explanation" is for teaching and is apparently not intended to be rigorous, and it doesn't tell you to make the "Reference" more than lists of individual items.
- skrebbel 3y ago
  Our “Reference” part starts with a “Concepts” before diving into details like the JS SDK, REST API etc. To me, concepts are just reference too, simply on a higher level of abstraction.
ritzaco 3y ago
In my experience, the model is very useful when writing a single doc. For questions like "Should we include x", the response can be "No, this is a guide not a tutorial, so the user needs to learn about x somewhere else", or whatever. I've seen several companies try to follow it pedantically as a structure for their docs (like literally having a sidebar with the four categories) and I've never seen that work out well, for the reasons explained in the article and the other comments here.
lornajane 3y ago
This article picks up some good points, but it seems like the main criticism is that Diataxis isn't useful for a programming language because that requires a sequence of lessons. But docs aren't a textbook, if you want to create a learning resource that's great - but that's not documentation IMO.
- kaycebasques 3y ago
  The textbook aspect of programming languages really is the key idea here IMO. There is something in the textbook example that doesn't seem to line up well with Diataxis's 4 modes of documentation. And IMO it totally does fall under documentation. If writing something like the Rust book is the difference between your project succeeding and failing, then that's the type of doc you've got to focus on. You can't not do the work just because it doesn't line up with some theory of doc types.
bazzargh 3y ago
I've never seen 4doc as a command to write all 4 things. The last few places I've worked, I've always asked "Can we hire a technical writer?", because if you've worked with one that's good at their job then they have a better idea how to organize docs than we coders do. But, short of that hire happening, 4doc helps point out where our docs are weak, by giving us a framework to discuss what any particular document 'is'. I usually find we've not got 4 kinds of documentation, but 2: a whole bunch of reference documentation, then a much smaller amount of tutorial, but little if any 'how-to' - which on the ops side, I find is what people are looking for. (the fourth kind, 'Explanation' is vanishingly rare, and usually only exists as tech talks) I feel devs are uncomfortable with writing good how-to's because they want it DRY: either it ends up as a bunch of links out to the reference doc ("here's the bits you need, some assembly required") or they make a doc full of "if A then B", to avoid repeating parts of their answer in multiple pages. This reads terribly. A little flexibility is ok, but choose-your-own-adventure is not; just write multiple pages answering specific questions, and don't worry about the repetition. In my current workplace, they've got stack overflow for teams filling this how-to role; I've seen many attempts at that fail due to lack of engagement but here a few people have pushed hard to make it useful and it's got some traction. We've even started using bookmarklets to pull conversations from slack and reformat them for SO.
- pm215 3y ago
  > A little flexibility is ok, but choose-your-own-adventure is not Now I'm wondering if you could write the how-to in Twine so that it automatically only shows the reader the parts relevant to them based on what they've chosen as they go through it :-) edit: and having read the article, I see Julia Evans had and executed that idea already -- wonderful!
Niksko 3y ago
At work, I attempted to structure our 'team documentation' (ways of working, run books, meeting notes, planning, that sort of stuff) this way. It was a disaster, didn't work at all. I agree with the author, a 'concepts' section is the big thing I find missing from the otherwise very useful 4 doc framework. This is also the most common addition that I see in open source projects, e.g. Istio and Kubernetes
miiiiiike 3y ago
Compare Django's (4doc) docs to Angular's impossible to follow non-documentation. I'll take Django's over Angular's any day.
stuaxo 3y ago
I've used Divios docs including the ones they used for DjangoCMS (two examples given of the four doc model) and both have gaps.
marcpaq 3y ago
Good article. Tech writer for too many years here: I agree with the 4 doc model. It boosts a proven structure for individual pieces of a doc set. DITA formalizes this with its topic, concept, and task, and reference topics. You see another form of it in man pages. And I agree with the FTA, it's often overkill or just plain unsuitable. If you're stuck with writing anything from a readme to an aircraft maintenance library, then you can make your content engaging and useful by just making sure that it's correct, clear, concise, consistent, and cohesive. Above all it should be compassionate[1]. Check off those 7 C's and your doc will be appreciated. The 4 doc model is just one option to get you there. [1] https://egopontem.com/blog/7cs https://egopontem.com/blog/7cs
regularfry 3y ago
Controversial opinion time: I don't think the Django docs are very good. I just find them hard to navigate, to the extent that rather than look for something as a howto or a reference, I'll go to the tutorial, because I already know it fairly well and I can find an example and probably a jumping-off point into the right section. It's often not obvious how to move around the site to find what you need, at all. I don't think this is the fault of the 4doc model, but I do think it's evidence that it's not all you need. As a case in point, all 4doc sites I've interacted with, as far as I can remember, have had documentation for how to use the documentation. That seems weird to me.
rkangel 3y ago
I talk in terms of an even simpler mental model that you might call the "Two-document model". All documentation really fits into two groups - "Reference level" documentation and "Guide level" documentation. Reference level would be any API references, function explanations, data types, protocol specifications etc.. Guide level includes tutorials, conceptual explanations, how to guides, examples. I find this to be a useful way of talking to people who need to produce some reasonable amount of documentation for something they're developing (or maybe some bare useful minimum). Often they will just write an API reference and think that they're done. By talking about "reference" and "guide" you can easily make it clear that they've got reference (kind of) covered, but they're missing and guides for how to get the SW built and then examples of how to use it.
kaycebasques 3y ago
Daniele [1], can you comment on this? > the original Divio page doesn’t have this disclaimer and instead has big quote calling it the “The Grand Unified Theory of Documentation”. Procida doesn’t seem to be believe this and I wish divio would stop pitching 4doc as the one-and-only documentation system This is a key point. I still equate Diataxis with this notion as the grand unified theory of documentation, because that's how it was originally billed. If Diataxis is no longer claiming to be anything close to a grand unified theory, then there's no point in debating whether it's universal or comprehensive. But the way that Diataxis talks about modes of documentation suggests to me that it still might be aiming towards universality and comprehensiveness. Put another way, are there other modes of docs that Diataxis doesn't mention? If these are the only 4 conceivable modes then doesn't that suggest that Diataxis is still aiming to be universal and comprehensive? I personally think that it's worthwhile to formulate it as an attempt at a grand unified theory because for one, most people agree that it's a useful foundation, and for two, the "modes of documentation" approach lends itself well to further refinement. It basically boils down to researching/discovering whether there are more modes of documentation out there and debating whether the 4 existing modes are truly the most fundamental modes. [1] The author of Diataxis who replied elsewhere in this thread
michaelhoffman 3y ago
I like the four-document model. While it isn't a perfect fit for all cases, for many it is a good start. We wrote a review of bioinformatics software documentation, which includes a taxonomy of research software documentation (Table 1) and examples of which popular bioinformatics software packages use each two (Table 2). It is clear that not every kind is needed for everything, and it's more of a menu than a prescriptive set of documentation types needed for everything: https://academic.oup.com/bib/article/19/4/693/2907814 https://academic.oup.com/bib/article/19/4/693/2907814
jasonlotito 3y ago
> there’s at least (at least) two more kinds of docs you’ll want: These already exist within the 4 models described. > Conceptual Overviews That's an explanation. It's covering the understanding. That's the purpose of that document. > (“Aren’t these just a kind of explanations?” Explanations are intended for people who already know, or are in the process of learning, your subject. It comes after the tutorial. Conceptual overviews come before the tutorial. They are for people who are getting ready to learn the subject, or for outsiders evaluating if they want to learn it.) This is wrong. When you start reading the documentation, you have started the process of learning. An explanation before is fine. The overview is literally a part of learning about the topic. Where it sits is immaterial. The purpose and the intent is important. > Snippets and Examples That's How-Tos. > Imagine I present you an example of a code, and then an example of the same code, optimized. I’m not giving you a rote how-to on optimizing code, I’m demonstrating a way of thinking about optimizing code. It all comes back to the mental model. You are demonstrating "how to think about optimizing code."

204 points by zdw 3y ago

Glad someone has written about this! We talk about the Diátaxis model a lot at Scribe (scribehow.com) where we feel like the how-to guide gets very little love from most of the traditional documentation platforms, which feel like they were all designed for reference material and not much else.

swyx 3y ago

I am also interested in alternatives to the 4 document model, having struggled with implementing/maintaining it with limited resources at 3 startups now. https://www.swyx.io/documentation-levels https://www.swyx.io/documentation-levels is my proposal. match documentation features to project maturity. 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 and so on (up to level 6 in the doc)

riwsky 3y ago
Know your audience, know your audience, know your audience.

ftxbro 3y ago

there are only four audiences so there can be only four document types

fsckboy 3y ago

I myself prefer the 5th document: Cheatsheet, with variety of not overly simple examples (where i can figure out that if I don't want an option I can leave it out, but now I know the option (TL;DR the other 4 are Tutorial, How-to Guides, Explanation, Reference)

HWR_14 3y ago
Snippets was brought up in the article, and seems reasonably equivalent to a cheatsheet.

nobeh 3y ago

Thanks for the interesting post and bringing a critical viewpoint. I am curious to learn about what other common best practices are around?

cratermoon 3y ago

The author previously discussed the four-document model and some additional kinds of documents at <https://buttondown.email/hillelwayne/archive/beyond-the-four-document-model/ https://buttondown.email/hillelwayne/archive/beyond-the-four...>, and goes into further detail about conceptual overviews and examples. Of the other kinds of documents he mentions, "Best Practices" are often the ones I look for early on when learning a new language or library. It's easier for me to get up to speed by emulating what works.

alexchamberlain 3y ago
Can we call it "Good Practices" instead, and make sure they qualify when they apply? Practices are rarely the best in all cases, and often change over time.
- inopinatus 3y ago
  There’s an argument to be made for documenting Worst Practices, too. Along with “Unsupported configurations”, “Practical limitations”, “Unmet use cases”, and “Failure modes”. That kind of information is absolute gold for solution design. Far too often I've found myself trying to discern the true envelope of some subsystem's capabilities by the negative space implied in the product docs, a task sometimes comparable to reading tea leaves. Alas, many product managers regard documentation as propaganda, thus in the interests of fragile egos such topics are commonly omitted.
  - cratermoon 3y ago
    I call the parts of my documents that address limitations and unmet use cases the "Not Gonna Do It" sections. In my case, it's especially important to document functionality that was considered and rejected, and why. Where performance, security, and similar qualities were recommended by programmers but rejected by management, I especially want to record those for later reference in case of problems. Maybe what I write doesn't make it into end-user facing product documentation, but it's on the record. To give an example, at one project I consulted on, all of the user interface text was written in english, with US measurements with no i18n or l10n system. The company I was working with has customers from, if not worldwide, at least all of the western hemisphere. About six months later project management finally came to the realization that they were going to need at the very least multiple languages, and a lot of work was ahead to retrofit.

inopinatus 3y ago

Very well, 6doc it is then.

exmadscientist 3y ago

The article's idea of Conceptual Overviews is something I find myself missing in a lot of projects' documentation. But I'd go even further. That paragraph about soup from the article? Every single piece of top-level documentation for any project anywhere should start with that paragraph. What is it? Who cares or should care? What can it do? When is it a good choice? I spend a lot of time searching, trying to decide if something is worth my time to research more. Writing that paragraph (and it really does need to be just one paragraph; I guess you can split it in two if you must) is very, very valuable to your prospective users! In the hardware world everyone does this: the first page of every datasheet tries to answer these questions. That's done not because it's required, but because it helps sell parts to engineers.

spondylosaurus 3y ago
There's a great tech writing book called Every Page is Page One[1] that changed how I write docs. Its primary conceit is basically what you've described: every single doc needs to immediately orient its reader, either with an intro paragraph or seamless hyperlinks to relevant background material (or, ideally, both). If the reader lands on a page that isn't right for them, it's the writer's job to leave a trail of breadcrumbs that leads them where they need to go. To grossly oversimplify, the EPPO page structure is almost like a Wikipedia article. Imagine you end up on the page for, idk, anthrax. If you already know a bit about yucky diseases and want to learn more, you'll read on. If you get a couple paragraphs in and you're like "wait, what exactly is a bacterium?", you can click the hyperlink to the relevant article about bacteria. And if you actually wanted to read about the metal band, there's an escape hatch to redirect you to the correct location. [1] https://everypageispageone.com/ https://everypageispageone.com/

vgivanovic 3y ago

Examples, examples, examples! Just today I failed to find an example of mounting multiple drives as one Btrfs filesystem. Plenty of how to create Btrfs filesystem examples. But how to mount them? Crickets. I eventually figured it out, but at a large cost in time.

wtallis 3y ago
I think you just wasted a lot of time looking for complexity that you wrongly expected to exist. When I google "btrfs mount multiple device", two of the top three results include exactly the example you needed to see (and probably skipped over believing it couldn't be that simple), and the other one indirectly explains what's going on by discussing the necessity of a btrfs scan when using multiple devices (and how to construct an fstab entry if your boot process doesn't do a btrfs scan). For the record: to mount a multiple device btrfs filesystem, use an ordinary mount command with any one of the block devices that are part of the file system. Every device contains information about what other devices are supposed to be part of that filesystem. I'm not sure if there are any techniques documentation writers can use to avoid this "hiding in plain sight" kind of problem.
- planede 3y ago
  > For the record: to mount a multiple device btrfs filesystem, use an ordinary mount command with any one of the block devices that are part of the file system. Every device contains information about what other devices are supposed to be part of that filesystem. If something works "automagically" like this then I jump into thinking about failure modes. Will it mount if one of the other devices are missing or failing? Will it just warn that the raid is degraded and I should add a new device? Will it mount read-only? > I'm not sure if there are any techniques documentation writers can use to avoid this "hiding in plain sight" kind of problem. The problem is probably lack of emphasis. It's guess it's hard to achieve in writing, if a solution is simple than you don't need many words to explain it, then it becomes easy to skip over.
  - wtallis 3y ago

kaycebasques 3y ago

My perspective as a technical writer of ~10 years. > In short, the 4doc model is not universal. It was designed for documenting tools and doesn’t fully address the needs of frameworks and programming languages. I think that the author is onto something here, but I'm not sold on the exact example that the author provides (programming languages). Honest question: are the Python docs deeply loved by the Python community? In other words, should we be holding up the Python docs as an example of great docs and therefore an example that the 4doc model is inadequate? I've done a fair bit of Python programming myself. In my experience the Python docs are decent: not great, not terrible. If we look at the Rust docs, which seem to get much more praise than the Python docs, then the author's argument seems to break down for me a bit. Because the Rust docs seem to be more aligned with the 4doc model than the Python docs, and the Rust docs are more praised than the Python docs. One domain where I recently saw the limitations of the 4doc model is OS bringup. I was writing docs explaining how to get an OS running on new hardware. Customer feedback suggested that the ideal doc would start off as an overview, and then morph into a guide, but the guide section would also need constant small explanations of conceptual stuff. I also agree with the "it's not comprehensive" premise but again the example fell flat for me. Conceptual overviews totally overlap with explanations. I can elaborate if needed but I honestly think the author is imposing a narrow definition of explanations that does not exist in the 4doc model. The main instances where the 4doc model is glaringly incomplete for me are homepages and release notes. You can kinda bucket homepages under explanations or references. And you can kinda bucket release notes under references. But those classifications are a stretch. The fact that practically every technical project needs a homepage and most need release notes really suggests to me that they are their own categories and deserve unique guidelines. The key here would be to go back to goal-focused thinking. My guess for the #1 reason for 4doc's success is how it aligns each doc type with a goal: * Tutorials - Learning * How-To Guides - Tasks * Explanations - Understanding * References - Information If you're going to propose a new universal doc type, you should be able to propose a new universal goal type as well. My argument about release notes begins to fall short here: release notes are totally about information so they should probably just get bucketed cleanly under references. But I think my argument about homepages holds its ground better: * Homepages - Convincing MAYBE (but probably not) we can save release notes like this: * Release Notes - Diffing The Pigweed docs might be an interesting example of where the 4doc model falls short. Here in SEED-0102 (our docs plan) you can see how the 4doc model is the foundation but we felt the need to define further categories of docs. In terms of domains (recall how the author suggested the 4doc is good for tools but not programming languages) Pigweed is a collection of a bunch of stuff for embedded development (libraries, tools, etc.) so that could explain why we needed to define more doc types. https://pigweed.dev/seed/0102-module-docs.html https://pigweed.dev/seed/0102-module-docs.html The topic of examples came up recently on the Write The Docs Slack. Daniele Procida had a very thoughtful response. Original comment from Rob H: > I tend to like to categorize some of my items by whether or not they have "examples," which seems to be an attribute that could apply to multiple diataxis types, but not a standalone type by itself. I could use a tag on these items with the word "examples," but I feel almost like it needs a category by itself, given that it seems to be my learning style. But then there's another twist: in some cases, an "example" is more of an "inspiration for a way to use something," and in others, an "example" is more of a "clarifier that completes the learning process." Response from Procida: > You can and probably should use examples everywhere. I think that a well-crafted example can often illuminate something much better than a painstaking attempt to describe it fully and completely. In every aspect of life in fact. I bet that you can think of someone who was an example to you, of say moral righteousness, that taught and inspired you more than any amount of moral theorising and argument (I certainly can). Examples are very powerful, and we are intelligent, so we use them very well when we encounter them. Examples illustrate extremely effectively, whether they are illustrating how-to guides, explanation, or whatever. But examples on their own seem a bit deracinated. What are they examples of? Don’t they need context?

onion2k 3y ago

The author makes a cogent argument but I can't help thinking they've fallen into a 'perfect is the enemy of good' trap. Sure, 4doc doesn't perfectly describe exactly how you should document everything, but it's better than every other approach I've encountered and that gives it a lot of value to me. It's likely that there isn't a documentation system that works perfectly for everything, especially if you accept an argument of 'this documentation system is a bit too verbose' which would stop you just enumerating everything imaginable. You have to be pragmatic. If your docs could be improved by adopting a 4doc approach then you should, because they'll be better docs for it, even if the system is technically flawed. Similarly, if you have a doc that doesn't fit anywhere in the 4doc system but it's a useful doc, then it's still worth adding. 4doc is a process. It is not perfect, but it's still useful, and you might need to step outside of it occasionally. That's fine.

brianpan 3y ago
The last section is titled "Good is the enemy of better".
sundarurfriend 3y ago
I don't think you and the author disagree at all. They say > I’m glad that people use it. I’m also a little frustrated that people use it even when its inappropriate. > I’ve read plenty of good 4doc pages. Even so, it still leads to the same kind of “this is the only way” thinking. People use the model even when it’s not the right choice and they don’t vary up the format even when they should. and you say > 4doc is a process. It is not perfect, but it's still useful, and you might need to step outside of it occasionally. --- The specific issue here is that it seems like the author has come across many people who use the 4doc model dogmatically. The article is geared specifically towards them, and is not an attempt to tear down the 4doc model as a whole.

throwawaaarrgh 3y ago

dumb people make grandiose statements and dumb people upvote it (aka the idiocracy model of culture). there will always be dumb popular models. make up your own, use that, move along

BiteCode_dev 3y ago

Yes, the 4 doc model is flawed, but if everybody followed it, we would still get on average 10 times better doc. When that happen, we can worry about improving, but most people are just terrible at explaining things. Also, how to guide are not more and more covered by chatgpt. But I don't think it should be a good reason to stop writing them. For example, I wrote an article on "Parameters, options and flags for Python scripts": https://www.bitecode.dev/p/parameters-options-and-flags-for https://www.bitecode.dev/p/parameters-options-and-flags-for This is typically the type of things you get great ROI with chatgpt. Yet: - it's still faster to copy the summary of the article - you need to understand the output of chatgpt so the article is useful to beginners - you need to be able to use the right words to ask chatgpt what you want, which again, implies you understand the problem - good practices and conventions are contextual, so the doc still helps On the other hand, it's hard to find a lone article on the net, most people will find it faster with chatgpt. But for your particular documentation of your particular product, that's still important to produce it. Because your best users will get familiar about your docs.

mjw1007 3y ago

I think the biggest weakness with the four-document model is that it doesn't have a proper place for rigorous documentation of the system's concepts and model. The biggest problem I find with software documentation is that the only rigorous part is a "Reference" which is organised as a list of functions or configuration options or commands or whatever, and while each individual item looks OK, they don't add up to a full description. One clue that you've got this problem is having reference items which use technical terms which aren't defined, or are only defined in the informal part of the documentation. Another form of this problem is a reference that's heavy on how options modify behaviour but omits any promises about the parts of the behaviour which are unconfigurable. The four-document model's division of "Explanation" and "Reference" doesn't help avoid this problem. The "Explanation" is for teaching and is apparently not intended to be rigorous, and it doesn't tell you to make the "Reference" more than lists of individual items.

skrebbel 3y ago
Our “Reference” part starts with a “Concepts” before diving into details like the JS SDK, REST API etc. To me, concepts are just reference too, simply on a higher level of abstraction.

ritzaco 3y ago

In my experience, the model is very useful when writing a single doc. For questions like "Should we include x", the response can be "No, this is a guide not a tutorial, so the user needs to learn about x somewhere else", or whatever. I've seen several companies try to follow it pedantically as a structure for their docs (like literally having a sidebar with the four categories) and I've never seen that work out well, for the reasons explained in the article and the other comments here.

lornajane 3y ago

This article picks up some good points, but it seems like the main criticism is that Diataxis isn't useful for a programming language because that requires a sequence of lessons. But docs aren't a textbook, if you want to create a learning resource that's great - but that's not documentation IMO.

kaycebasques 3y ago
The textbook aspect of programming languages really is the key idea here IMO. There is something in the textbook example that doesn't seem to line up well with Diataxis's 4 modes of documentation. And IMO it totally does fall under documentation. If writing something like the Rust book is the difference between your project succeeding and failing, then that's the type of doc you've got to focus on. You can't not do the work just because it doesn't line up with some theory of doc types.

bazzargh 3y ago

I've never seen 4doc as a command to write all 4 things. The last few places I've worked, I've always asked "Can we hire a technical writer?", because if you've worked with one that's good at their job then they have a better idea how to organize docs than we coders do. But, short of that hire happening, 4doc helps point out where our docs are weak, by giving us a framework to discuss what any particular document 'is'. I usually find we've not got 4 kinds of documentation, but 2: a whole bunch of reference documentation, then a much smaller amount of tutorial, but little if any 'how-to' - which on the ops side, I find is what people are looking for. (the fourth kind, 'Explanation' is vanishingly rare, and usually only exists as tech talks) I feel devs are uncomfortable with writing good how-to's because they want it DRY: either it ends up as a bunch of links out to the reference doc ("here's the bits you need, some assembly required") or they make a doc full of "if A then B", to avoid repeating parts of their answer in multiple pages. This reads terribly. A little flexibility is ok, but choose-your-own-adventure is not; just write multiple pages answering specific questions, and don't worry about the repetition. In my current workplace, they've got stack overflow for teams filling this how-to role; I've seen many attempts at that fail due to lack of engagement but here a few people have pushed hard to make it useful and it's got some traction. We've even started using bookmarklets to pull conversations from slack and reformat them for SO.

pm215 3y ago
> A little flexibility is ok, but choose-your-own-adventure is not Now I'm wondering if you could write the how-to in Twine so that it automatically only shows the reader the parts relevant to them based on what they've chosen as they go through it :-) edit: and having read the article, I see Julia Evans had and executed that idea already -- wonderful!

Niksko 3y ago

At work, I attempted to structure our 'team documentation' (ways of working, run books, meeting notes, planning, that sort of stuff) this way. It was a disaster, didn't work at all. I agree with the author, a 'concepts' section is the big thing I find missing from the otherwise very useful 4 doc framework. This is also the most common addition that I see in open source projects, e.g. Istio and Kubernetes

miiiiiike 3y ago

Compare Django's (4doc) docs to Angular's impossible to follow non-documentation. I'll take Django's over Angular's any day.

stuaxo 3y ago

I've used Divios docs including the ones they used for DjangoCMS (two examples given of the four doc model) and both have gaps.

marcpaq 3y ago

Good article. Tech writer for too many years here: I agree with the 4 doc model. It boosts a proven structure for individual pieces of a doc set. DITA formalizes this with its topic, concept, and task, and reference topics. You see another form of it in man pages. And I agree with the FTA, it's often overkill or just plain unsuitable. If you're stuck with writing anything from a readme to an aircraft maintenance library, then you can make your content engaging and useful by just making sure that it's correct, clear, concise, consistent, and cohesive. Above all it should be compassionate[1]. Check off those 7 C's and your doc will be appreciated. The 4 doc model is just one option to get you there. [1] https://egopontem.com/blog/7cs https://egopontem.com/blog/7cs

regularfry 3y ago

Controversial opinion time: I don't think the Django docs are very good. I just find them hard to navigate, to the extent that rather than look for something as a howto or a reference, I'll go to the tutorial, because I already know it fairly well and I can find an example and probably a jumping-off point into the right section. It's often not obvious how to move around the site to find what you need, at all. I don't think this is the fault of the 4doc model, but I do think it's evidence that it's not all you need. As a case in point, all 4doc sites I've interacted with, as far as I can remember, have had documentation for how to use the documentation. That seems weird to me.

rkangel 3y ago

I talk in terms of an even simpler mental model that you might call the "Two-document model". All documentation really fits into two groups - "Reference level" documentation and "Guide level" documentation. Reference level would be any API references, function explanations, data types, protocol specifications etc.. Guide level includes tutorials, conceptual explanations, how to guides, examples. I find this to be a useful way of talking to people who need to produce some reasonable amount of documentation for something they're developing (or maybe some bare useful minimum). Often they will just write an API reference and think that they're done. By talking about "reference" and "guide" you can easily make it clear that they've got reference (kind of) covered, but they're missing and guides for how to get the SW built and then examples of how to use it.

kaycebasques 3y ago

Daniele [1], can you comment on this? > the original Divio page doesn’t have this disclaimer and instead has big quote calling it the “The Grand Unified Theory of Documentation”. Procida doesn’t seem to be believe this and I wish divio would stop pitching 4doc as the one-and-only documentation system This is a key point. I still equate Diataxis with this notion as the grand unified theory of documentation, because that's how it was originally billed. If Diataxis is no longer claiming to be anything close to a grand unified theory, then there's no point in debating whether it's universal or comprehensive. But the way that Diataxis talks about modes of documentation suggests to me that it still might be aiming towards universality and comprehensiveness. Put another way, are there other modes of docs that Diataxis doesn't mention? If these are the only 4 conceivable modes then doesn't that suggest that Diataxis is still aiming to be universal and comprehensive? I personally think that it's worthwhile to formulate it as an attempt at a grand unified theory because for one, most people agree that it's a useful foundation, and for two, the "modes of documentation" approach lends itself well to further refinement. It basically boils down to researching/discovering whether there are more modes of documentation out there and debating whether the 4 existing modes are truly the most fundamental modes. [1] The author of Diataxis who replied elsewhere in this thread

michaelhoffman 3y ago

I like the four-document model. While it isn't a perfect fit for all cases, for many it is a good start. We wrote a review of bioinformatics software documentation, which includes a taxonomy of research software documentation (Table 1) and examples of which popular bioinformatics software packages use each two (Table 2). It is clear that not every kind is needed for everything, and it's more of a menu than a prescriptive set of documentation types needed for everything: https://academic.oup.com/bib/article/19/4/693/2907814 https://academic.oup.com/bib/article/19/4/693/2907814

jasonlotito 3y ago

> there’s at least (at least) two more kinds of docs you’ll want: These already exist within the 4 models described. > Conceptual Overviews That's an explanation. It's covering the understanding. That's the purpose of that document. > (“Aren’t these just a kind of explanations?” Explanations are intended for people who already know, or are in the process of learning, your subject. It comes after the tutorial. Conceptual overviews come before the tutorial. They are for people who are getting ready to learn the subject, or for outsiders evaluating if they want to learn it.) This is wrong. When you start reading the documentation, you have started the process of learning. An explanation before is fine. The overview is literally a part of learning about the topic. Where it sits is immaterial. The purpose and the intent is important. > Snippets and Examples That's How-Tos. > Imagine I present you an example of a code, and then an example of the same code, optimized. I’m not giving you a rote how-to on optimizing code, I’m demonstrating a way of thinking about optimizing code. It all comes back to the mental model. You are demonstrating "how to think about optimizing code."