[HN Gopher] A Framework for Writing Better Documentation
___________________________________________________________________
A Framework for Writing Better Documentation
Author : omginternets
Score : 340 points
Date : 2021-02-02 16:08 UTC (6 hours ago)
(HTM) web link (documentation.divio.com)
(TXT) w3m dump (documentation.divio.com)
| austincheney wrote:
| 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...
| spratzt wrote:
| This is excellent. It looks like jupyterbook!
| jerkstate wrote:
| I saw this talk at pycon a few years ago and it changed how I
| think about documentation, great concepts!
| TameAntelope wrote:
| 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!
| milani wrote:
| This is very useful and practical. I never thought about
| documentation in this way.
| acemarke wrote:
| 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
| jayparth wrote:
| 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!
| acemarke wrote:
| 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
| lars_francke wrote:
| 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.
| blt wrote:
| 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.
| ldes wrote:
| 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...).
| stsewd wrote:
| Another way to achive this is in sphinx is using
| https://github.com/executablebooks/sphinx-tabs
| formerly_proven wrote:
| 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...
| stsewd wrote:
| Sphinx tabs supports that
| https://github.com/executablebooks/sphinx-tabs#grouped-
| tabs, haven't used sphinx-inline-tabs
| xixixao wrote:
| 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").
| DanieleProcida wrote:
| 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.
| RandomWorker wrote:
| 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!
| kaycebasques wrote:
| 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.
| k__ wrote:
| _" 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 wrote:
| Implementation experience reports come to mind.
| twinprime wrote:
| Also curious myself..
| kaycebasques wrote:
| 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)
| DanieleProcida wrote:
| 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.
| dvaun wrote:
| Thank you for your summary of these items and for providing
| references.
| ericholscher wrote:
| 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 :)
| miller_joe wrote:
| 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.
| jzer0cool wrote:
| 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.
| nmg wrote:
| 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.
| dang wrote:
| A large related thread from 2019:
| https://news.ycombinator.com/item?id=21289832
| wyck wrote:
| 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?
| afterwalk wrote:
| 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.
| eandre wrote:
| 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.
| sambroner wrote:
| 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.
| jmalin wrote:
| 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.
| formerly_proven wrote:
| 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.
| ericholscher wrote:
| 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.
| dnmfarrell wrote:
| > 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 wrote:
| 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.
| paul_manias wrote:
| You say that like someone that is yet to experience the
| absolute hell that is OpenSSL 'documentation'.
| jmalin wrote:
| 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
| FriedrichN wrote:
| >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 wrote:
| 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.
| calcsam wrote:
| This framework is both very insightful and quite actionable. In
| December we explicitly restructured our documentation to follow
| this pattern: https://gatsbyjs.com/docs
| DanieleProcida wrote:
| 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).
| LockAndLol wrote:
| 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.
| eloycoto wrote:
| Woww, this is great, thanks for sharing
| tomd wrote:
| 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.
| [deleted]
| mratsim wrote:
| 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/
| steveklabnik wrote:
| 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.
___________________________________________________________________
(page generated 2021-02-02 23:00 UTC)