Hacker News

The Grand Unified Theory of Documentation

2021-04-1518:5714057diataxis.fr

A systematic framework for technical documentation authoring. The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding…

A systematic framework for technical documentation authoring.

The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.

The Grand Unified Theory of Documentation

- David Laing

The framework identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation.

Each of these modes (or types) answers to a different user need, fulfils a different purpose and requires a different approach to its creation.

'overview of the documentation system'

In other words, what we call documentation is fundamentally not one thing, but four. Understanding the implications of this will help improve most documentation - often immensely.

Diátaxis promises to make documentation and projects better, and the teams that work with them more successful.

While redesigning the Cloudflare developer docs, this content framework became our north star for information architecture. When we weren’t sure where a new piece of content should fit in, we’d consult the framework. Our documentation is now clearer than it’s ever been, both for readers and contributors.

- Adam Schwartz (@AdamSchwartz)

The framework is light-weight, easy to understand and straightforward to apply. It doesn’t impose implementation constraints.

If you’d prefer to watch a video covering this topic, here is it (courtesy of PyCon Australia 2017).


Read the original article

shafte

Karma: 387
...
 @Hacker__News
@hacker._news

Comments

  • By rglover 2021-04-1522:275 reply

    Some personal rules for docs:

    1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why.

    2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it).

    3. Think in terms of a blog post/tutorial, not technical API docs as a starting point. This helps with adoption because people want to understand the thing first and then dig into API (just because you may not doesn't mean that others are the same).

    4. Don't be lazy. Show respect for the people taking the time to use your stuff and put in the effort (grammar, structure, quality of examples, etc).

    • By npunt 2021-04-165:021 reply

      Agree to all! When I was rewriting the OneSignal docs I followed the same rules you laid out as well as a few more:

      5. Get every step right. Don't make assumptions that the reader knows how to configure something you mention in passing, spell it out. This is especially important if good engineers are writing docs since they leap over little things that less skilled users might not know.

      6. Write for translators. Many users don't speak English well and will be running docs through Google Translate. This is a variant of your #1.

      7. Consider docs a seamless extension of the product. Use the exact wording and same visual language of the product and make sure docs pick up from where exactly the user was in the product. Evaluate these flows so wherever someone gets tripped up, the right doc is there waiting. Ideally do bidirectional linking so the product itself also links to these.

      8. Super consistent language. Figure out your nouns and verbs: someone playing a game is always a 'player' (vs sometimes a 'user' or 'gamer'), someone sending a file is always 'transferring' (vs sometimes 'sending' or 'uploading'), etc. Unless you pay close attention ambiguity is going to creep into documentation.

      • By eru 2021-04-165:092 reply

        About 8: this habit might make your docs sound a bit monotonous, but it also helps with 'grepping' through them.

        • By vicda 2021-04-167:35

          We don't read documentation to entertained, but to solve problems. How searchable your text is extremely important.

        • By neetrain 2021-04-165:182 reply

          I don't know whether it is only in my country, but teachers in school teach students otherwise. Not repeating the same word for the same things is alright for elegant literature, but problematic in the digital era.

          • By eru 2021-04-165:27

            Yes, literature and technical documents have different requirements.

          • By bobthepanda 2021-04-1615:58

            At least in the US my undergrad computer science degree had a course on specifically writing technical documentation

    • By chillfox 2021-04-164:353 reply

      "(no foobar)"

      As someone with English as a second language seeing "foobar" all over the place in lot's of different contexts really confused me a lot early on. Especially when docs started talking about a "foo" and a "bar".

      I still don't understand why it is the generic go to word for examples, it makes little sense.

      • By ansible 2021-04-167:17

        The word "foobar" has a long, long history in computers:

        http://www.catb.org/~esr/jargon/html/F/foo.html

      • By Vinnl 2021-04-166:011 reply

        Likewise when learning OOP long ago, it seemed like every tutorial used a car with wheels and a steering wheel as examples. Took me a long time afterwards to understand how it could actually be used in practice.

        • By chillfox 2021-04-167:07

          Yeah, the entire car, engine and wheels thing really disconnected OOP from any practical use for me. It really took a long time before I understood how it applied to real code.

          If real examples from a blog or accounting software had been used instead then I would likely have understood it a lot easier.

      • By eru 2021-04-165:11

        I guess it's a combination of people following earlier example, and that it sounds funny.

        In economics textbooks, companies always produce 'widgets'. https://en.wikipedia.org/wiki/Widget_(economics)

    • By hinkley 2021-04-160:181 reply

      I find that people tend to bristle at #1, in part because they tend to think about 'the document' instead of the giant pile of documents that will be produced over the next 3 years, and the fact that sooner or later you're going to be skimming multiple documents to figure out which one had the fix for that one problem or explained why on earth we made some dumb decision a year ago. This is most obvious with Wikis but it applies to an extent to all documentation.

      Remind me why I'm here in this document, because I might be in the wrong place.

      • By eru 2021-04-165:13

        Your point reminds me that you shouldn't think about documentation as a one-off thing you are doing for your project.

        But in terms of a process. Eg how are you going to keep the docs up to date?

    • By johnchristopher 2021-04-167:384 reply

      It may be due the language barrier or something but there are some phrasing that really throws me of:

      > You might send variables to this server function by calling this endpoint from your javascript code.

      You might but in fact you must (or you can) because it is the only way send variables to the server from Javascript. It's not like it's a personal preference or that there is another way.

      > You can choose to use `register_rest_route()` to register a custom route [..].

      But this is the only way to register a route.

      • By unwind 2021-04-169:50

        I couldn't figure out what you are quoting, but to me "sending a variable" signals major confusion with the author, in the general case.

        Values (being data) can be transmitted, actual variables (being programming-language constructs to contain values and make them available to operate upon) cannot.

      • By samus 2021-04-1612:15

        The wording "might" really triggers me because it stands for something that /could/ happen. It is one of the ways to express the conjunctive mood (possibilities, wishes, ambiguity), which has absolutely no right to exist in a technical documentation.

        ~~There is only one place where this makes sense: in a best-practices section explaining consequences. But also there I want to see clear facts instead of unclear statements making me chase ghosts.~~

        Edit: No, just plain facts please.

      • By toomanybeersies 2021-04-1613:42

        This is where RFCs get it right (although technically they're standards, not documentation), with standardised language [1]

        e.g.

        > MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.

        [1] https://tools.ietf.org/html/rfc2119

      • By JimDabell 2021-04-167:49

        As with most things, you can improve the writing by removing unnecessary words:

        > You might send variables to this server function by calling this endpoint from your javascript code.

        …becomes:

        > send variables to this server function by calling this endpoint

        …and:

        > You can choose to use `register_rest_route()` to register a custom route [..].

        …becomes:

        > Use `register_rest_route()` to register a custom route [..].

    • By MaxDPS 2021-04-1819:09

      I like your point about condescending language. I’ve found myself using phrases like “It’s easy” in an attempt to not scare people away, but I see how that can backfire. I’m going to keep that in mind.

  • By formerly_proven 2021-04-1519:514 reply

    In case you went "hey, this looks like a blatant rip-off of Divio's pages, doesn't it?" -- yeah it is, because this is the spin-off of that particular aspect from Divio.

    • By acemarke 2021-04-1520:27

      Yeah, I _was_ sorta wondering that, actually :) I think it went from being a single blog post, to its own subdomain, and now to a totally different site? Kinda weird progression.

      Love the advice overall, and I've tried to apply that as I've been reworking the Redux core docs.

      (Gotta say the new name's kinda odd, though.)

    • By Vosporos 2021-04-167:30

      Yep' it would seem that Daniele Procida left Divio and hosts the Documentation System on its own domain now

    • By dnautics 2021-04-162:021 reply

      can you provide a reference link so that some of us can understand Divio? Thanks!

      • By FinalAngel 2021-04-168:24

        www.divio.com > documentation.divio.com (also docs.divio.com where it is applied)

    • By swyx 2021-04-1520:511 reply

      wait so... this is a spinoff startup? i didnt even know what Divio sells..

      • By DanieleProcida 2021-04-168:571 reply

        Divio is a cloud management/application hosting platform. We use Docker for containerisation, and provide a unified integration layer to multiple different underlying vendors (AWS, Azure, etc).

        It means you can use the same tools (Control Panel, CLI, API) to create and manage cloud applications and their infrastructures on all those different vendors.

        The idea is that Divio takes care of infrastructure/DevOps concerns so that customers can concentrate on developing applications and products. https://www.divio.com

        Feel free to ask me more.

        • By swyx 2021-04-1615:13

          thanks for the explanation!

          i personally dont have this need at all (all in on AWS, and am ex Netlify and very friendly with Render) so havent really needed a unified integration for multiple vendors. good luck!

  • By remoquete 2021-04-167:421 reply

    It's funny how little things have changed since software documentation started. Have a look at the Guideline for Software Documentation Management (1984 https://nvlpubs.nist.gov/nistpubs/Legacy/FIPS/fipspub105.pdf)

      Documentation fulfills five important functions:
    - Communications to management about the progress of 
      the project, providing intermediate product
      visibility
    - Task-to-task communication
    - Instruction and reference
    - Quality assurance support
    - Historical reference
    The biggest thing I'm missing from this nice little diagram is that in order to do documentation properly, you need people dedicated to it. That is, writers.

    • By kungito 2021-04-169:341 reply

      I'm very against this. You need resources allocated, that is developer time. I experienced having dedicated doc writers in FAANG and I wasn't happy with the experience. Our docs were mostly shit and for anything remotely specialized it was the developers who had to write the docs in the end. They were mostly proofreading or writing some non technical blog posts. It felt like they were an excuse for not forcing the developers to write proper docs themselves, and in the end no one wrote the technical docs most of the time.

      • By remoquete 2021-04-1610:42

        So your argument against technical writers is that you've had bad experiences with FAANG technical writers? And you think developers always have the time and skill for writing proper documentation? I wish that was true.

        For certain types of documentation you need technical technical writers - for example, see http://hackwrite.com/posts/enough-to-be-dangerous/. And you need a proper content strategy / information architecture in place. Blame your recruiting managers and whoever wrote the job descriptions for not thinking about that.

        Edit: And of course you need to allocate developer time. It's called knowledge transfer.

HackerNews

About