A Framework for Writing Better Documentation | Hacker News Reader

A Framework for Writing Better Documentation

documentation.divio.com

637 pointsomginternets76 comments

I review a lot of technical software documentation. This is one of my go-to resources for explaining how docs should be organized. These ideas are generally accepted among software technical writers; you may just hear them use slightly different words for each doc type. E.g. I use "overview" instead of "explanation". I'll also mention that this framework isn't comprehensive; there are other types of critical documents that aren't explained here, such as release notes. I think the key breakthrough with Divio's framework is getting authors to think about docs in terms of desired goals and outcomes: learning-oriented, problem-oriented, etc.

Edit: I suppose you could argue that release notes fall under the category of reference-oriented, but when I look at the guidelines for reference docs it's clear that the Divio people were thinking about API references.

"this framework isn't comprehensive; there are other types of critical documents that aren't explained"

Do you have more examples for things missing here?

Implementation experience reports come to mind.

Introductions. The Divio site itself starts with an introduction yet it's not listed as one of the content types! You could argue that introductions fall into the understanding-oriented category but when I read the guidelines about explanations it's not particularly clear how to write a good introduction, and the goal feels somewhat different. I think the principles of information foraging [1] are probably most helpful towards understanding how to create a good introduction.

Announcements (similar to release notes but focused on a single topic). We do these a lot on web.dev. Journalistic principles can help a lot towards creating useful announcements: answer the 5 Ws [2], inverted pyramid [3], etc.

Case studies. In this case the goal is to persuade the reader to make a change and to do that you need to focus on what's in it for them. The journalistic principles mentioned earlier are also very helpful here.

Code samples. How do you organize a big collection of code samples for easy discoverability? Some projects make small code samples in the spirit of how-to guides (i.e. the code samples only show how to do one particular task), other people do them more in the spirit of tutorials (i.e. it shows you a working end-to-end realistic application). The best approach is probably to do both. Again I think the Divio framework can help guide these decisions, but looking at the Divio framework narrowly, there's nothing explicitly focused on code samples. One might argue that code samples aren't documentation, but in my experience a single good code sample sometimes gets the job done much better than any of content types that Divio mentions.

[1] https://en.wikipedia.org/wiki/Information_foraging

[2] https://en.wikipedia.org/wiki/Five_Ws

[3] https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)

Thank you for your summary of these items and for providing references.

You should submit a talk to one of our Write the Docs conferences (https://www.writethedocs.org/) -- this is a great start to a talk abstract :)

Daniele Procida already has a great Write the Docs talk on this subject already. It is indeed a fantastic talk.

https://youtu.be/qK-AnF5FJTs

Thanks for the kind words!

You are quite right, there are various things that aren't included in the scheme, that ought to be included in a complete set of documentation.

Other examples could be: release notes (though you could include them in reference), contribution guide (though it could be part of how-to) and of course, the Introduction you mention.

Mostly I think that these things probably belong outside the scheme, in the same way that say an appendix or an introduction falls outside main body of text in a book.

An introduction (in documentation) is basically marketing: a reason for someone to keep reading.

For me the scheme is not so much a complete list of every kind of thing that must be written (I think it goes without saying that you need to create useful contents tables for example) as a guide to how I should be writing and a reminder why I am writing.

> Mostly I think that these things probably belong outside the scheme

Yeah, I think somethings count as "meta documentation" and are "documentation about the documentation" instead of the actual documentation.

"contribution guides" to me are definitely that, "introductions" are mostly that. I reckon licenses are probably "meta documentation" too (since they'll also be in the source code). "release notes" are a bit of a grey area in my head (I'd consider at least major version update release notes and any depreciation/removal of features to be "part of the doco".

I honestly also think it is worth mentioning introductions as an essential part. I somewhat disagree that it is outside the scope of a scheme of documentation.

An introduction to both the system goals and overall architecture provide essential context for the rest of the documentation, and can even provide the scaffold to structure it around.

It is all too common for writers of documentation (deeply embedded in the project) to forget that the person reading the documentation may have no clue what the whole system is trying to achieve (especially so in public-facing documentation... how many times do you see a link on HN to a documentation page with no explanation of what "a BUZZY GRAPHEME WRANGLER" actually is?).

Also... by your analogy, I am fairly certain that a guide to writing a technical book would dedicate a fairly considerable amount of space to the topic of a good introduction ;)

I don't disagree about the importance of introductions.

I can't count the number of times I've looked at the home page of documentation for some product and it has felt like stumbling into a teenagers' conversation conducted entirely incomprehensible references, slang and in-jokes.

An introduction needs to say what the thing is, what it does and why someone might want to use it. Usually that can be expressed in a few sentences.

I don't really see it as a mode of documentation in the way that the four components I describe are.

I wouldn't worry too much though. The framework isn't intended as a "do this, all this and nothing but this or you're doing it wrong" final statement on the art of documentation.

It's more a tool for thinking about what you are writing, for whom, and how you can best write it for them. It's to be used however someone finds it useful.

Also curious myself..

Speaking for myself, two items I often find missing: the overall summary and the rationale.

Many times I've gone to a set of documentation wondering what exactly the thing _is_. Let's take the JavaScript language, for example. The very first thing that should be documented is a short description of what exactly JavaScript _is_. This could be a single sentence, should probably be at least a paragraph, and should be no more than a page. It boggles my mind how often this critical piece of information is omitted entirely.

The rationale quickly orients the reader to the landscape of similar solutions. It's very rare that something has no peer of any kind, and it's quite useful to understand why this particular thing exists, and how it can be distinguished from other similar solutions. The Python language, for example, has a number of attributes that separate it from other computer languages. This can be concrete (it comes with constraints that lend themselves to readable programs), or they can be aspirational (Python aspires to be an easy language to pick up, particularly for non developers). This can go deep, and rapidly descends into matter that my be quite useful and interesting, but belongs in an appendix or other separate matter.

FAQs and code comments don't really fall cleanly into any of these categories.

Greg Wilson writes about a useful tool for thinking about types of documentation [0] incorporating the novice-competent practitioner-expert framework.

It looks like he was at least partly inspired by this article [1].

[0] https://third-bit.com/2019/08/08/documentation-types/

[1] https://third-bit.com/2018/10/18/four-forms-of-docs/

I used this resource as inspiration for when I had to rewrite the documentation for my JS library[1]. There's still a lot of work involved - particularly when it comes to finding the enthusiasm to write up another tutorial lesson or 'How Do I?' note but - overall - the documentation I have now is a lot easier to maintain and update as the library evolves.

How useful it is for others ... I don't know the answer to that one. But knowing the documentation satisfies my needs (it's a Big Library; I'm constantly forgetting small details about how to use it) is enough for me.

[1] - https://scrawl-v8.rikweb.org.uk/

A lot of the origin of this work is from Jacob Kaplan-Moss who did the original refactor of the Django documentation. He wrote up the concepts here in 2009:

https://jacobian.org/series/great-documentation/

Daniele Procida built on this and formalized it through this resource, which is really amazing and definitely the best resource for writing docs that I know of.

I've been working on an ongoing rewrite for the Redux core docs [0], including writing a couple brand new comprehensive tutorials from scratch [1]. In the process, I collected a bunch of notes and resources on useful docs writing advice [2]. My two favorites by far are this Divio docs writing guide, and the Vue docs writing style guide [3]. Excellent resources!

[0] https://github.com/reduxjs/redux/issues/3592

[1] https://redux.js.org/tutorials/index

[2] https://github.com/reduxjs/redux/issues/3609

[3] https://v3.vuejs.org/guide/contributing/writing-guide.html

In the past the Redux docs were something that was really hard for me to follow. I can't be super precise with my feedback, but the docs weren't able to cleanly explain the concepts and the React example was hard to follow. I had to learn from Youtube tutorials.

Thanks for rewriting them!

You're welcome! We've actually gotten many compliments about our docs over the years, but per that "Overview" issue, there's a lot of improvements that can be done. Also, "modern Redux" code with Redux Toolkit and the React-Redux hooks API is very different than the Redux code you'd have written even just a couple years ago, and we wanted to teach those approaches as the default. We also added a "Style Guide" page [0] that lists our recommended best practices, and that's been a big help for a lot of people.

Sadly, we can't do anything about the tens of thousands of existing Redux tutorials out there, and I keep seeing people post new Redux tutorials even now that don't make any mention of RTK at all. Kinda frustrating, but all I can do is keep trying to improve our docs, answer questions, and let people know that it's a lot easier to learn and use Redux today.

[0] https://redux.js.org/style-guide/style-guide

To be fair, a lot of people that started their project a few years ago might never have heard of redux toolkit. I only know of it because I read hackernews.

I don’t think I really ever have to look at the redux docs, which probably doesn’t help.

Yeah, that's one of my ongoing frustrations as a maintainer :) I've always gone straight to a tool's docs when I want to start learning it. I look for other sources, too, but I start with the docs, and I always assumed other people did, too. That's definitely not the case - many people deliberately _don't_ look at docs [0].

I definitely don't expect everyone with an existing Redux codebase to know that RTK exists already (although sure, I'd love to wave a magic wand and update every Redux codebase to RTK overnight). But it is sad to see new tutorials being posted that A) don't teach anything new compared to the plethora of existing tutorials, and B) continue to teach older patterns that are the same things people have complained about Redux over the years.

So, even though I'm spending a lot of time updating our docs and highlighting RTK as the default way to use Redux, many people just rely on whatever other courses and tutorials they've looked at for their knowledge.

[0] https://twitter.com/acemarke/status/1213898963679633411

To your point, I had never heard of Redux toolkit or those hooks. Thank you for sharing!

That would be great because the redux doc read like dark wizardry the reader isn't worthy to glaze upon.

Hmm. Any specific points of concern with the docs at this point?

I think it's a typo but "unworthy to glaze upon" is hilarious

This looks like a great resource, thank you for sharing.

One trick I learned many moons ago from a tech writer was what he called the "SEE" method - statement, example, explanation. I've never found any references to it. I've found it effective for simple cases such as helping engineer's "just get started" to break writer's block. It's not a grand theory covering all doc types.

I've never heard that but I like it.

A similar (sub)concept: The Code Sandwich

Any demonstrative code block should be "sandwiched" between a sentence of introduction above and an explanation of what the code is doing below.

As someone who is anal about writing documentation and wants to give a great big hug to whoever writes good documentation, this part made me chuckle:

"Nearly everyone understands this. Nearly everyone knows that they need good documentation, and most people try to create good documentation. And most people fail."

In my experience, no, most people I've worked with couldn't care less. It's sad. Some people can't even be bothered to write good bug reports, features requests, or tasks...

Maybe it’s more that they try, but fail to find any motivation to write something as mind-numbingly boring as documentation?

I guess I fail to see how writing documentation is boring. At least for software, I am writing about what I built. I am trying to help people use my software or library. If I value the product of my labor, how could that be boring?

I have a semi-related question: I'm looking for a customizable documentation system.

I'd like the typical docs in Markdown or Asciidoc in flat files like a static CMS but within a page I'd like to have customer/choice dependent blocks.

So some free form text and then a block with instructions that are different per environment or customer or whatever. So based on a selection I'll only show the parts for Debian or Red Hat or whatever or I'll pull customer information out of a CMS system to show the customer only the parts relevant for her environment.

I know this exists but I can't find an example now. This is what I'd like to avoid: https://docs.nginx.com/nginx/admin-guide/installing-nginx/in... I don't want to show a Debian user all the stuff she's not interested in.

Pytorch has a really good one for installation, but it seems to be handcrafted JavaScript. I would love if .rst on readthedocs offered some declarative way to do it.

As mentioned above, sphinx-tabs will get the job done.

One way to achieve this is using Sphinx (documentation generator based on reStructuredText https://www.sphinx-doc.org/en/master/) in combination with the Contentui extension (https://sphinxcontrib-contentui.readthedocs.io/en/latest/tab...).

Another way to achive this is in sphinx is using https://github.com/executablebooks/sphinx-tabs

sphinx-inline-tabs is probably better for this use case because all tabs with the same label are synchronized on the page. So if you want to offer different instructions for a number of environments, you only need to select it once per page.

Example: https://pip.pypa.io/en/stable/installing/#installing-with-ge...

Sphinx tabs supports that https://github.com/executablebooks/sphinx-tabs#grouped-tabs, haven't used sphinx-inline-tabs

We just launched a hosted wiki service called Miki that can be customized in this way. You can control page content by setting up custom groups and permissions and you can integrate with other APIs to do things like get user settings from another source.

We'll have an offline, desktop version soon. http://miki.mimix.io

I used to work somewhere that didn't take documentation as seriously as it should and I personally 'suffered' as a result because as a reviewer I spent a lot of time fixing poorly written docs, or explaining to others how they should fix them.

I finally got management's attention when I stood up in one of our periodic group wide meetings and said "There is something that we do that is critical to our business but very inefficient because of the level of rework it triggers. Across a year we start this activity about once every two hours. What is it?"

The answer was of course 'create a document'. I'd used our document issuing system to find out how many docs our group had created in a year. As a group that conducted research tasks and process-heavy delivery projects for external customers, we did in fact create a lot of documents. We already had a document guidance framework, but it wasn't until management realised the overhead created by not following it that the necessary training and education in doc production finally got traction.

Technical documentation is so underrated. I find it is a make or break situation and should be as important to the software development cycle. Maybe a SWE and good technical writer is hard to find? A lot of times we are pressured and rewarded for code, bug fixes, etc., rather than to document. I find often the reverse to be true although not proven. If documentation is well kept and maintained, I wonder how much time is given back over it's course? Just like code, documentation is also iterated and improved upon.

As food for thought, what changes would occur if documentation must be created first before any coding takes place? How about if produced in parallel? Too often, it is an artifact at the end.

Quad charts are used extensively in the US military.

https://en.m.wikipedia.org/wiki/Quad_chart

Examples: https://www.rechargecolorado.org/army-quad-chart-template-pp...

Interesting; they kinda look like condensed pitch decks.

Are they ever used for anything besides pitching, i.e. after a project is completed?

I mostly see them used for staff operations: major updates, next 24 hours, misc, risks/concerns

Chiming in with the "as a documentation writer, this seems great to me." I gave a talk at the Bay Area Rust Meetup in 2013 that laid out a similar framework, specific to Rust. http://steveklabnik.github.io/rust_documentation/#/

This is much cleaner and not specific to a programming language. Gonna save this link for sure.

Just spent 2 months refactoring the documentation on besos.readthedocs.io after this talk (watch the YouTube video attached to the article) I want to go back and restructure it again! Love talks like this, I always had a sense that one part of my documentation is different from other part. I did understand purpose of these parts of the documentation but there was and is a lack of structure. This talk gives me the definitions and vocabulary to articulate that sense of frustration and some tools to solve it. Thanks for sharing!

This framework is both very insightful and quite actionable. In December we explicitly restructured our documentation to follow this pattern: https://gatsbyjs.com/docs

That's really great to see it used in Gatsby's documentation, I wasn't aware of that. And I like the way you say e.g. "Practical step-by-step guides to help you achieve a specific goal. Most useful when you're trying to get something done." under each heading, it hadn't occurred to me that it would be good to state that explicitly like that.

To complete the circle, https://divio.com is built in Gatsby (not the documentation though; that's in RST/Sphinx and published on readthedocs.com).

Daniele Procida - the author of this framework - is giving a talk about it at the start of Wagtail's documentation sprint on Thursday:

https://wagtail.io/docs-sprint-details

Do join if you're interested, even if it's just to hear Daniele's talk.

Thanks, I do think it's useful and practical to think about docs this way in four quadrants, and identify where your current document should live on the plane.

FastAPI's docs (recently front page on HN) are a great example of focused, concise documentation that knows exactly its purpose.

I'm a technical writer. The framework not only captures the modern thinking about documentation, it expands upon it by using a 2-dimensional approach. Nearly all TWs use a variation of this framework.

It's interesting to see how classic MSDN documentation from the 90s is structured quite literally like this.

- xxx: One to two paragraph introduction

- About xxx: Generally explanation

- Using xxx: A bunch of how-to's

- xxx Reference: (id.)

The Tutorials quadrant is notably (and noticeably) absent and is what was then supplied by so many other places.

Thanks for this, can anyone recommend what actual tool they prefer to write, publish, and manage documentation with? I'm aware of Sphinx, etc but I'm considering just using one of the many markdown related static generators, is something with a back-end(cms) better?

I write technical docs in Asciidoc format using AsciidocFX, I use Asciidoctor to convert to HTML, and Asciidoctor PDF to convert to PDF - It's a workflow I'm really happy with.

I love this framework and I have been using before the website redesign when it didn't have a dedicated subdomain.

I have convinced my colleagues at work to use it as well: https://nimbus.guide/

I really like the system and it seems there's also a temporal order to the learning path:

1) Tutorials <- starting point 2) How To <- intermediate 3) Reference <- comes back to it regularly 4) Discussion <- final step to understanding

However as the video mentions, it's all connected in a circle, as perhaps having some discussion up-front(why, context, alternatives) is useful for newcomers to evaluate whether this project is worth diving into.

Curious as to whether the author(and everyone) thinks on how much "discussion" should be put into the "Getting Started" page.

A large related thread from 2019: https://news.ycombinator.com/item?id=21289832

I'm currently rewriting (maybe just "writing", it's pretty sparse) the documentation for FluidFramework.com and I can't believe I just found this incredibly useful resource!!

Some of it is intuitive, but it's just great to have such a structured perspective.

This submission comes at the perfect time. I've been working on improving the docs for Encore for the past week, and while I was aware of different types of documentation, this does an excellent job breaking it down and making it concrete.

Let’s say I want to write a “best practices” guide - where does it fall? Should each topic contain all 4 quadrants?

Example topic is “Explicitness vs conciseness in naming” (it could be (over)simplified to “prefer explicit over concise naming”).

Perfect example (in the scheme) of an explanation/background/key concepts/discussion/whatever you call it document.

That's where you weigh up options, discuss alternatives, etc. If it's something you could read about in the bath or talk about over dinner, it goes there.

Perhaps, but I'm not sure it's so clear cut. The best practice should be concrete - it should have code examples. It should be beginner friendly (since it's beginners who will use it most often).

Great "best practices" example is just now on homepage: https://startup-cto.net/10-bad-typescript-habits-to-break-th...

I'll try this out, thanks. Never gave it real thought and have always tried to somehow organize my documentation. Maybe this will get it right.

I saw this talk at pycon a few years ago and it changed how I think about documentation, great concepts!

Outdated documentation is worse than no documentation.

It doesn't matter which framework was used to write it.

This is very useful and practical. I never thought about documentation in this way.

> It doesn’t matter how good your product is, because if its documentation is not good enough, people will not use it.

Eh docs aren't that important; we've all used badly documented libraries before. Would better docs help? Sure, but let's not overstate their value.

The framework looks like a useful writing aid though.

I agree that it's overstated: people will use it if forced, even if the docs are terrible or non-existent. Companies like Stripe are examples of how transformative a good docs experience can be, though.

You say that like someone that is yet to experience the absolute hell that is OpenSSL 'documentation'.

Depends on the product and the competition.

If no other library suffices, then customers will use yours. But they'll hate you. Over time, they might stop using your other contributions, even if they don't have any other choice.

In other words, would better/faster/more easily modified code help? Sure, but let's not overstate its value. We've all used badly designed code before. /s

>we've all used badly documented libraries before

Sure have, way too often. But if there's a choice, I'll pick the one with proper documentation every time (unless it's absolutely inferior of course).

The interesting part to me is the notion of cost for the product: how much you pay upfront, or how much you intend to pay in integration work etc.

With cost in mind, documentation quality brings the total cost up or down and can change the calculation entirely. It’s also implicitly taken into account when a team builds a POC and reports the time spent on it. Depending on if it took 3 weeks or 5 days, it will be a completely different perspective.

This is excellent. It looks like jupyterbook!

Woww, this is great, thanks for sharing

I love stuff like this. Folks can argue the specifics on their merits and they're welcome to (and should!), but really, having any system that takes the meta-thinking out of the equation is, IMO, a helpful improvement.

It's kind of like fitness -- you can do a million different things, but doing something is better than doing nothing at all. Just pick that something and go!

Reply on news.ycombinator.com