10 ms·
A Framework for Writing Better Documentation
- nmg 6y agoThanks, 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.
- RandomWorker 6y agoJust 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!
- jerkstate 6y agoI saw this talk at pycon a few years ago and it changed how I think about documentation, great concepts!
- calcsam 6y agoThis framework is both very insightful and quite actionable. In December we explicitly restructured our documentation to follow this pattern: https://gatsbyjs.com/docs https://gatsbyjs.com/docs
- DanieleProcida 6y agoThat'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 https://divio.com is built in Gatsby (not the documentation though; that's in RST/Sphinx and published on readthedocs.com).
- LockAndLol 6y agoI'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.
- spratzt 6y agoThis is excellent. It looks like jupyterbook!
- TameAntelope 6y agoI 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!
- milani 6y agoThis is very useful and practical. I never thought about documentation in this way.
- kaycebasques 6y agoI 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.
- k__ 6y ago"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?
- hyperion2010 6y agoImplementation experience reports come to mind.
- kaycebasques 6y agoIntroductions. 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 https://en.wikipedia.org/wiki/Information_foraging [2] https://en.wikipedia.org/wiki/Five_Ws https://en.wikipedia.org/wiki/Five_Ws [3] https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism) https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)
- sambroner 6y agoI'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.
- acemarke 6y agoI'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 https://github.com/reduxjs/redux/issues/3592 [1] https://redux.js.org/tutorials/index https://redux.js.org/tutorials/index [2] https://github.com/reduxjs/redux/issues/3609 https://github.com/reduxjs/redux/issues/3609 [3] https://v3.vuejs.org/guide/contributing/writing-guide.html https://v3.vuejs.org/guide/contributing/writing-guide.html
- jayparth 6y agoIn 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!
- acemarke 6y agoYou'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 https://redux.js.org/style-guide/style-guide
- jayparth 6y ago
- lars_francke 6y agoI 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/installing-nginx-open-source/ 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.
- blt 6y agoPytorch 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.
- blt 6y agoAs mentioned above, sphinx-tabs will get the job done.
- ldes 6y agoOne way to achieve this is using Sphinx (documentation generator based on reStructuredText https://www.sphinx-doc.org/en/master/ https://www.sphinx-doc.org/en/master/) in combination with the Contentui extension (https://sphinxcontrib-contentui.readthedocs.io/en/latest/tabs.html https://sphinxcontrib-contentui.readthedocs.io/en/latest/tab...).
- stsewd 6y agoAnother way to achive this is in sphinx is using https://github.com/executablebooks/sphinx-tabs https://github.com/executablebooks/sphinx-tabs
- 6y ago
- eandre 6y agoThis 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.
- dnmfarrell 6y ago> 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.
- kaycebasques 6y agoI 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.
- paul_manias 6y agoYou say that like someone that is yet to experience the absolute hell that is OpenSSL 'documentation'.
- jmalin 6y agoDepends 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
- FriedrichN 6y ago>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).
- hrktb 6y agoThe 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.
- mratsim 6y agoI 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/ https://nimbus.guide/
- dang 6y agoA large related thread from 2019: https://news.ycombinator.com/item?id=21289832 https://news.ycombinator.com/item?id=21289832
- jmalin 6y agoI'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.
- formerly_proven 6y agoIt'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.
- steveklabnik 6y agoChiming 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/#/ http://steveklabnik.github.io/rust_documentation/#/ This is much cleaner and not specific to a programming language. Gonna save this link for sure.
- miller_joe 6y agoThis 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.
- andrenotgiant 6y agoI'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.
- ericholscher 6y agoA 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/ 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.
- wyck 6y agoThanks 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?
- GordonS 6y agoI 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.
- deleted 6y ago[deleted]
- xixixao 6y agoLet’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”).
- DanieleProcida 6y agoPerfect 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.
- xixixao 6y agoPerhaps, 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).
- xixixao 6y agoGreat "best practices" example is just now on homepage: https://startup-cto.net/10-bad-typescript-habits-to-break-this-year/ https://startup-cto.net/10-bad-typescript-habits-to-break-th...
- tomd 6y agoDaniele 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 https://wagtail.io/docs-sprint-details Do join if you're interested, even if it's just to hear Daniele's talk.
- eloycoto 6y agoWoww, this is great, thanks for sharing
- austincheney 6y agoQuad charts are used extensively in the US military. https://en.m.wikipedia.org/wiki/Quad_chart https://en.m.wikipedia.org/wiki/Quad_chart Examples: https://www.rechargecolorado.org/army-quad-chart-template-ppt/ https://www.rechargecolorado.org/army-quad-chart-template-pp...
- scribu 6y agoInteresting; they kinda look like condensed pitch decks. Are they ever used for anything besides pitching, i.e. after a project is completed?
- austincheney 6y agoI mostly see them used for staff operations: major updates, next 24 hours, misc, risks/concerns
- jzer0cool 6y agoTechnical 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.
- afterwalk 6y agoI 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.
- KineticLensman 6y agoI 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.
- systematical 6y agoAs 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...
- Aeolun 6y agoMaybe it’s more that they try, but fail to find any motivation to write something as mind-numbingly boring as documentation?
- systematical 6y agoI 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?
- amai 6y agoOutdated documentation is worse than no documentation. It doesn't matter which framework was used to write it.