The Grand Unified Theory of Documentation(diataxis.fr)
diataxis.fr
The Grand Unified Theory of Documentation
https://diataxis.fr/
57 comments
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.
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.
About 8: this habit might make your docs sound a bit monotonous, but it also helps with 'grepping' through them.
We don't read documentation to entertained, but to solve problems. How searchable your text is extremely important.
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.
Yes, literature and technical documents have different requirements.
At least in the US my undergrad computer science degree had a course on specifically writing technical documentation
"(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.
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.
The word "foobar" has a long, long history in computers:
http://www.catb.org/~esr/jargon/html/F/foo.html
http://www.catb.org/~esr/jargon/html/F/foo.html
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.
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.
If real examples from a blog or accounting software had been used instead then I would likely have understood it a lot easier.
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)
In economics textbooks, companies always produce 'widgets'. https://en.wikipedia.org/wiki/Widget_(economics)
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.
Remind me why I'm here in this document, because I might be in the wrong place.
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?
But in terms of a process. Eg how are you going to keep the docs up to date?
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.
> 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.
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.
Values (being data) can be transmitted, actual variables (being programming-language constructs to contain values and make them available to operate upon) cannot.
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.
~~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.
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
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
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 [..].
> 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 [..].
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.
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.
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.)
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.)
Yep' it would seem that Daniele Procida left Divio and hosts the Documentation System on its own domain now
can you provide a reference link so that some of us can understand Divio? Thanks!
www.divio.com > documentation.divio.com (also docs.divio.com where it is applied)
wait so... this is a spinoff startup? i didnt even know what Divio sells..
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.
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.
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!
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!
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
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.
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.
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.
I've been trying to apply this approach, and it's generaly been a useful way of forming a holistic view of your docs.
The only quadrant that can be a bit challenging is the explanation: some projects are just relatively straightforward and don't require a lot of background knowledge about the whys. In that case, I've found it best to just stick to a couple of lines on the homepage explaining the project's background and the problems it's solving, rather than a separate, rather barren-looking section of your docs.
The only quadrant that can be a bit challenging is the explanation: some projects are just relatively straightforward and don't require a lot of background knowledge about the whys. In that case, I've found it best to just stick to a couple of lines on the homepage explaining the project's background and the problems it's solving, rather than a separate, rather barren-looking section of your docs.
That's fine. Or a single "Explanation" or "About all this" page. Or just a paragraph on the main page.
The scheme is not a plan that must be fulfilled, it's a guide or map to help you see where you are and where you need to go.
However, don't be ashamed of barren-looking things. They are OK. The reader won't mind.
The scheme is not a plan that must be fulfilled, it's a guide or map to help you see where you are and where you need to go.
However, don't be ashamed of barren-looking things. They are OK. The reader won't mind.
What I personally do when stuff is straightforward is question how and why it is straightforward to me.
Usually, I realize it is because it's following whatever is my framework's way of doing things, or it is following the usual specs of the tools I use. In this case, I make a conscious effort to dig up a link to a tutorial on a "standard project", and link it there, an example would be:
> This project is following a Classic Java Spring Architecture (-> links to the spring tutorial), with this and this modification...
You have to imagine that people happening upon your documentation might have a totally life experience than you, they may even be a lowly intern, thrown to your project as the sole maintainer of your code, with only school-taught experience.
Usually, I realize it is because it's following whatever is my framework's way of doing things, or it is following the usual specs of the tools I use. In this case, I make a conscious effort to dig up a link to a tutorial on a "standard project", and link it there, an example would be:
> This project is following a Classic Java Spring Architecture (-> links to the spring tutorial), with this and this modification...
You have to imagine that people happening upon your documentation might have a totally life experience than you, they may even be a lowly intern, thrown to your project as the sole maintainer of your code, with only school-taught experience.
I find this troublesome because it attempts to categorize documentation in a synthetic way and then stops. While that's totally fine and a field on its own, this is not how people learn. It's akin as to saying that to learn French you need to categorize words as "substantives", "adjectives", "verbs", etc. Sure it's slightly useful, but it's just not how people approach learning.
Instead, and I mean to eventually write this long-form, I find it a lot more useful to think of documentation as a learning experience. You need several levels: for those who don't even know they want to learn it, for the beginners, for the seasoned that need a quick ref, for the ones who just lack practice, etc. In this way, tutorials will cater for a specific type of learners while the API docs will be a reference for those with already experience.
That is why I will also argue that library authors tend to go to the API docs. I read the docs of my own libraries, so while I have a feeling how it works I might want to quickly check the format of e.g. the second options argument. Since I wrote it, it's very useful for me to document the API since I already know how to get started or why to even use it. But that's not the same for others.
So I will argue that from the landing page (if any) to the API docs, there's no a strong divide and you should start teaching the user from the beginning. As an example, my projects tend to include a few-lines snippet as soon as possible.
PS, to do great documentation is a full-time job, and I still maintain that some ideal-ish ratio of lines of code vs testing vs documentation, given all the time in the world to work on it, is 1:5:10. as in, for each 1 line of code there should be 10 lines/paragraphs of documentation.
Instead, and I mean to eventually write this long-form, I find it a lot more useful to think of documentation as a learning experience. You need several levels: for those who don't even know they want to learn it, for the beginners, for the seasoned that need a quick ref, for the ones who just lack practice, etc. In this way, tutorials will cater for a specific type of learners while the API docs will be a reference for those with already experience.
That is why I will also argue that library authors tend to go to the API docs. I read the docs of my own libraries, so while I have a feeling how it works I might want to quickly check the format of e.g. the second options argument. Since I wrote it, it's very useful for me to document the API since I already know how to get started or why to even use it. But that's not the same for others.
So I will argue that from the landing page (if any) to the API docs, there's no a strong divide and you should start teaching the user from the beginning. As an example, my projects tend to include a few-lines snippet as soon as possible.
PS, to do great documentation is a full-time job, and I still maintain that some ideal-ish ratio of lines of code vs testing vs documentation, given all the time in the world to work on it, is 1:5:10. as in, for each 1 line of code there should be 10 lines/paragraphs of documentation.
I agree, and I encourage you to write all that down in a long form article. Technical writers and documentarians have kept silent for too long: It's time to change this.
Hi everyone. I'm Daniele, author of the framework.
It now has its own domain, because it's about time. This is where it will continue to be updated and maintained.
A quick clarification: I am still at Divio, but after a break in June I'll be looking for something new.
If you have a notable product, a large developer user-base, a positive internal culture, and need to address some significant challenges in developer education/documentation, at the highest level - get in touch: [email protected]
I should also like to point out that when I posted this a week or so ago, it got just three points https://news.ycombinator.com/item?id=26724825. Very unfair.
It now has its own domain, because it's about time. This is where it will continue to be updated and maintained.
A quick clarification: I am still at Divio, but after a break in June I'll be looking for something new.
If you have a notable product, a large developer user-base, a positive internal culture, and need to address some significant challenges in developer education/documentation, at the highest level - get in touch: [email protected]
I should also like to point out that when I posted this a week or so ago, it got just three points https://news.ycombinator.com/item?id=26724825. Very unfair.
Eyup Daniele, it's great to see this get some recognition and visibility. It's a very useful framework for documentation.
Best of luck with the job hunt..!
Best of luck with the job hunt..!
> I should also like to point out that when I posted this a week or so ago ...
To be fair, when the article was posted under its Divio url a year ago it got 717 likes and 199 comments - https://news.ycombinator.com/item?id=21289832
I'll not repost the comment I made on that thread (because: too many spammy links) but the advice in the article is good; I wish more people would follow the recommendations.
To be fair, when the article was posted under its Divio url a year ago it got 717 likes and 199 comments - https://news.ycombinator.com/item?id=21289832
I'll not repost the comment I made on that thread (because: too many spammy links) but the advice in the article is good; I wish more people would follow the recommendations.
I love this doc because while it's not staying the whole story, it was basically my conclusion as well: you can't have one doc, you need several of them for different use cases.
I would had to the mix a page where jargon is defined, like a lexicon. You cannot, and should not always get away with jargon. Sometime you should (beginner tutorial), sometime you should define it inline (advanced tutorial), and sometime you should just use it (references), but with link it to the definition.
I would had to the mix a page where jargon is defined, like a lexicon. You cannot, and should not always get away with jargon. Sometime you should (beginner tutorial), sometime you should define it inline (advanced tutorial), and sometime you should just use it (references), but with link it to the definition.
I would consider "a page where jargon is defined, like a lexicon" to be a perfect example of reference material.
In the video, the names of the four documentation categories are not the same as those listed in the diagram near the top of the webpage.
If you are in a rush, the diagram is all you really need. The lecture is needlessly long, even played at double speed.
If you are in a rush, the diagram is all you really need. The lecture is needlessly long, even played at double speed.
Django documentation has been following a similar model since the early days. Mostly, I believe, thanks to dedicated work of Jacob Kaplan-Moss, who also wrote a really good series of articles on the topic[0] (you’ll probably notice some parallels there).
[0] https://jacobian.org/2009/nov/10/what-to-write/
[0] https://jacobian.org/2009/nov/10/what-to-write/
In regards to that four-quadrant infographic - how could Technical Reference fall into the category of "theoretical knowledge?"
I'd think tutorials would fall under theoretical because if it gets too practical, are you not effectively writing a how to guide?
I'm not really sure the four categories fit into that quadrant scheme as well as they'd like.
I'd think tutorials would fall under theoretical because if it gets too practical, are you not effectively writing a how to guide?
I'm not really sure the four categories fit into that quadrant scheme as well as they'd like.
I'm not sure why this is being downvoted. I'll throw in my two cents (not the OP or anything):
It's not theoretical knowledge in the sense of "theoretical/applied physics", but rather theoretical knowledge because there is an extra step between it and application.
So if I give you a list of functions in a module/class and just tell you what they do, that is more theoretical than a code block that you can cut and paste as running code.
I'm not sure how else you would label this axis, theory/practical seems just fine.
It's not theoretical knowledge in the sense of "theoretical/applied physics", but rather theoretical knowledge because there is an extra step between it and application.
So if I give you a list of functions in a module/class and just tell you what they do, that is more theoretical than a code block that you can cut and paste as running code.
I'm not sure how else you would label this axis, theory/practical seems just fine.
This is a good question.
Practical knowledge is knowing how to do something - tie your shoelaces, instantiate a model class, authenticate to an LDAP server.
Theoretical knowledge is knowing what is the case - that the cross-flow valves must be closed at take-off, that everything in Python is an object, what a Python property decorator does.
Technical reference is theoretical knowledge (that you apply in practice), as is explanation. Tutorials and how-to guide contain practical knowledge.
Practical knowledge is knowing how to do something - tie your shoelaces, instantiate a model class, authenticate to an LDAP server.
Theoretical knowledge is knowing what is the case - that the cross-flow valves must be closed at take-off, that everything in Python is an object, what a Python property decorator does.
Technical reference is theoretical knowledge (that you apply in practice), as is explanation. Tutorials and how-to guide contain practical knowledge.
The single most important rule for documentation, which most projects get wrong, and carries you 80% of the way:
"It should exist".
"It should exist".
Doesn't the existence of blogs and Q&A sites like Stackoverflow indicate that current approaches to documentation are failing to deliver. I think there's more to the rise of cut & paste development than simply a lack of skill or a lack of time. The volume of state in some software systems is simply too great to put down in a linear document. Indeed the number of branches in state maybe too great to represent in any meaningful way or in any timeframe that's practical.
If you look at a framework like Django. The documentation is generally considered excellent. However now there is simply so much stuff that many complex things get only a cursory treatment. So everybody heads over to SO to find the question that is the closest fit to theirs.
I am not sure what would be better or indeed if there is any solution to this. The framework here layout a multidimensional approach with tutorials to get started and reference to follow up with. However creating documentation systems with that level of complexity is an enormous task and for anything of any quality, an enormous cost.
So what's the answer? I'm not sure there is one.
If you look at a framework like Django. The documentation is generally considered excellent. However now there is simply so much stuff that many complex things get only a cursory treatment. So everybody heads over to SO to find the question that is the closest fit to theirs.
I am not sure what would be better or indeed if there is any solution to this. The framework here layout a multidimensional approach with tutorials to get started and reference to follow up with. However creating documentation systems with that level of complexity is an enormous task and for anything of any quality, an enormous cost.
So what's the answer? I'm not sure there is one.
If you look at certain languages, usage of such spaces is much more limited. For example, Elixir's docs are absolutely phenomenal, which leads to discussion being dominated by much harder problems than "how do I use X".
The article here covers the idea pretty well. You need to cover all 4 parts of documentation, and it should definitely be all available in official documentation, rather than relying on lower-discoverablity third parties.
The article here covers the idea pretty well. You need to cover all 4 parts of documentation, and it should definitely be all available in official documentation, rather than relying on lower-discoverablity third parties.
Why shouldn't the creation of knowledge and expertise come with a price tag? The question is "is it cheaper to create a system that creates new expertise than it is to hire someone with that expertise?" As long as the cost of the system is less than the cost of the generated expertise on the open market, it's a worthwhile investment.
Sure, we could assign price tags to every human interaction and never stop. But isn't it better for everyone to build a collective wiki of knowledge that we can all share and rely on? If I spend an entire day digging through the webpack documentation to perform a certain task, I'll gladly share that knowledge freely with anyone who asks, because I think it's a complete waste of human existence for each of us individually to learn how to wrangle webpack into submission.
The question becomes: If I've already put in the work, what cost is there to me to make my knowledge freely available in the form of a SO answer? Usually the answer is "not much".
(I'll be sending you an invoice for this comment)
The question becomes: If I've already put in the work, what cost is there to me to make my knowledge freely available in the form of a SO answer? Usually the answer is "not much".
(I'll be sending you an invoice for this comment)
My impression was that people went to SO to solve issues, and to documentation to think and build features.
I’d see those as complementary, and don’t expect documentation to cover most questions/issues you could have.
I’d see those as complementary, and don’t expect documentation to cover most questions/issues you could have.
Depends on the doc. If I have to do something with Django, VueJS or TailwindCSS, I always go to the doc first (mostly looking things up with "site:" in google though), because most of the time, it delivers.
If I have to create a db with one owner in postgres, I will not use the postgres docs.
If I have to create a db with one owner in postgres, I will not use the postgres docs.
Yes please. Documentation is so under developed. Most engineers funny know how to create it. This should be a critical skill that is covered with multiple full length classes in college. Learning how to write good docs will teach you how to write good code
Suggestion: join Write the Docs (https://www.writethedocs.org/). It's a welcoming tech writing community.
I love this. A concise mental model for documentation, an oft maligned but necessary evil.
Arrogant much? At least he admits it up front, as if that excuses it. It's funny what people tell you if you just listen.
TL;DR Be aware of your intended audience.
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).