I think the important question to answer is actually why should you produce good docs. Is it to inboard new devs quicker? To help experienced devs find information faster? To act as a first line of support to reduce questions from third parties using your API? Maybe a bit of everything?
It'll vary from project to project depending on the audience. There's no such thing as definitively "good docs" that would work for everyone, but you certainly can make good docs for a given project if you know what your audience needs. Ask that question first.
> The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.
Like the "What nobody tells you about documentation" post that was going round recently, this one says that the way to write your "final source of truth" documentation is to document each individual function and assume that that adds up to a complete description.
I think this is often bad advice. It's too easy to find documentation of this sort that misses out describing key aspects of how the software actually promises to behave.
For example, you might have a graphics library with lots of functions for creating pens and coordinate systems and so on, all meticulously documented, and then one "render" function with a brief description that tells you what the return type is, but no description of (say) the layering or composition model, because that doesn't belong to any one function.
Instead, I recommend starting by documenting the key behaviour of the program, describing its model of the world and defining terminology, and only then trying to document each function in terms of that model and terminology.
One of my favorite writings on the matter is Teach, Don't Tell, by Steve Losh: http://stevelosh.com/blog/2013/09/teach-dont-tell/ , including a rather savage takedown of wikis as a documentation mechanism. A bit idealistic, perhaps, especially for open source or single-person projects, but a good north star for doc work IMO.
It's good advice, but I think that like a lot of such articles it's talking about how to run, when there's a need for more articles on how to walk.
That is, the first duty of technical documentation is to be complete and correct (at least for practical purposes). Once you've got that far it's time to pay attention to optimising it for the needs of your likely readers.
> Instead, I recommend starting by documenting the key behaviour of the program, describing its model of the world and defining terminology, and only then trying to document each function in terms of that model and terminology.
Can you explain in more detail how that's different from the approach described in "What nobody tells you about documentation"? [0] At first blush, your recommendation sounds pretty similar to what is suggested in that post.
Is this a critique of the guideline to "Give reference documentation the same structure as the codebase" that was in [0], or is it more like you think the importance of the "Explanation" section is underrated?
(This is coming purely from the perspective of somebody who is trying to write better documentation. I'm not trying to defend any particular stance, just interested in your opinion.)
- B: a description of a model, its operations, and terminology
The other is
- X: "the only job is to describe, as clearly and completely as possible", vs
- Y: "a chance to relax and step back"
My reading of the "what nobody tells you" article is that it envisages a reference which is A and X, and an explanation which is B and Y.
I recommend that the reference should be A, B, and X. Having an explanation which is B and Y is a fine thing too.
So basically the bit I don't like in that article is where it says the reference should not attempt to explain basic concepts. Maybe it doesn't need to try to teach concepts, but it very often does need to define them.
(Also, I think rationale fits well in the "describe as clearly and completely as possible" document, especially if you're in a position to separate it a bit from the main text.)
Ah, that makes a lot of sense. Thanks for the very clear explanation! It makes me think perhaps that's one of the things that the Postgresql docs are so good at -- hitting that "B+X" quadrant in their reference docs. I'll definitely keep that in mind!
In my experience (as a technical writer) the best documentation approaches it from both angles. The top-down approach connects all the pieces together, as you mentioned, and the bottom-up approach gives the nitty-gritty details that implementers need. That's why conceptual overviews and references are 2 of the most common content types.
I think the main error I see when developers try to create a lot of docs, vs the most common "uniformly underdocument", is to get twisted in a pretzel over what point or detail to include when, eventually splattering all of it into one form(whether that be tutorial, API reference, or some other idea) while still not covering everything because when you explain everything you eventually end up crossing over into being a programming tutorial.
The more systematic approach which I've really caught onto recently is to assume it has to be atomized a bit to get any breathing room. Make distinct spaces for the narratives, spaces for basic concepts and references, spaces for formal overviews, and spaces for single tasks, features and APIs. Then have them link to each other, using the link as the leverage to let each part of the documents use the necessary vocabulary without overexplaining. While it's possible to overdo that and produce documentation that is a thicket of links, just clarifying that you have a distinct purpose to the space makes the writing process much more systematic - no confusion over what the writing needs to concentrate on.
"document each individual function and assume that that adds up to a complete description."
Every major system for converting function documentation to code has a slot for documentation at the top of the module/package/class/whatever. I find this is very underused, almost across the board. I actually quite like automatic documentation, on the provision that you put something decent at the top for people to orient with.
I think you will find this documentation one for the ages:
Listen to our President Donald Trump demand a $4 billion dollar bribe from child rapists to "turn a blind eye" on January 3rd, 2019.
Download the video, turn the volume all the way up and put head phones on. Trump is on a call from with Henry Porter and Gigi Hadid. (See Page 63) Bribe demand at 1018am:
You might want to save this post. It will be censored when this account logs off.
Listen to Speaker of the House, Senator Nancy Pelosi, accept a $3 billion dollar bribe from wealthy high profile child rapists for safe passage to get Asian boys through the border at "Monterrey" on January 17, 2019.
Download the video, turn the volume all the way up and put head phones on. Call starts at 10:31am.
Speaker of the House Nancy Pelosi returns to the Porter camera system at 1031 for a check-in. "Nancy Pelosi is here and she wants $3 billion to keep the border open at Monterrey. $3 billion dollars to keep that shit open do you believe that?" Matthew Porter commentates. Pelosi states 1034: "I think he [Brian Schlenker] needs to be removed. I think we need to get this guy out of here". Speaker Pelosi then agrees to call back at 7pm PST. Gigi Hadid at 1034: "Thanks for calling us. I've got you down for three minutes". Pelosi don't worry about that I've got 3 billion.
1031 Matthew Porter: Nancy Pelosi is on and she wants $3 billion dollars to keep the border open at Monterrey. Three billion dollars to keep that shit open do you believe that?
1033 Nancy Pelosi: I don't think that will be necessary unless you insist.
1033 Donald Reeves?: We insist.
1033 Nancy Pelosi: Ok then I guess we have a deal.
1033 Matthew Porter: Thank you Mrs. Pelosi.
1033 Nancy Pelosi: Please call me Speaker Pelosi.
1033 Nancy Pelosi: We want to make sure you have safe passage at Monterrey.
1033 Matthew Porter: We appreciate that Speaker Pelosi.
1033 Gigi Hadid: I think we may have to scale back a little bit though.
1033 Nancy Pelosi: Gigi I think we'll be just fine.
1035 Nancy Pelosi: God damn it! I want Kamala to get a billion out of yours, not out of mine.
1035 Gigi Hadid: I think we can accommodate you but we need to find out if Monterrey will be open on the 30th of January.
1036 Nancy Pelosi: Of course it will Gigi.
1036 Nancy Pelosi: $3 billion goes a long way Peter.
1036 Peter Thiel: Excellent answer.
1043 Gigi Hadid: I think we need to give Kamala a billion dollars to keep her [happy].
1043 Matthew Porter: I think we can do that but we need to get her to do something first.
1043 Gigi Hadid: She did. We got her fucking Rahm Emmanuel Monday morning [14Jan] at 235.
1043 Matthew Porter: Perfect, then we're all set. Send her the billion.
1043? Nancy Pelosi: She'll accept the money, I guarantee it.
1043? Gigi Hadid: Nancy thank you for everything.
<ch4>
1036 Donald Reeves: Don't listen to her. She will close down the border if it's not there. Make sure she gets the $3 billion.
On web.dev we've started to create documentation quality guidelines [1] and a concrete, step-by-step checklist for ensuring that each document meets our quality guidelines. Long-term plan for the guidelines is to prioritize them based on research, and to link to research justifying why each guideline maps to quality. Feedback welcome, and LMK if you know of any other "style guides" already doing this.
I appreciate it when creators provide introductory material in a top-down, inverted pyramid style. When I’m reading that sort of documentation, I am probably investigating tools for solving a problem and perhaps comparing different options. A quick summary that confirms I’ve found the right sort of thing — or that warns me immediately if I haven’t — and that sets out its distinguishing features and priorities is helpful. Following that with an overview of the main concepts and structure with some concise examples of typical use cases gives a flavour of what it’s like to use this tool in practice and provides some context for any larger examples or more comprehensive reference material.
This starts right from the first sentences describing the tool. I am a particular fan of people who don’t hide the purpose of the tool behind several lines of adjectives and credits. The Redis description in the article is exemplary, IMHO.
23 comments
[ 3.9 ms ] story [ 58.8 ms ] threadIt'll vary from project to project depending on the audience. There's no such thing as definitively "good docs" that would work for everyone, but you certainly can make good docs for a given project if you know what your audience needs. Ask that question first.
I know it's not quite your point, but the article http://stevelosh.com/blog/2013/09/teach-dont-tell linked elsewhere (https://news.ycombinator.com/item?id=21339009) proposes:
> The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.
I prefer the more general approach to documentation given here: https://www.divio.com/blog/documentation/
I think this is often bad advice. It's too easy to find documentation of this sort that misses out describing key aspects of how the software actually promises to behave.
For example, you might have a graphics library with lots of functions for creating pens and coordinate systems and so on, all meticulously documented, and then one "render" function with a brief description that tells you what the return type is, but no description of (say) the layering or composition model, because that doesn't belong to any one function.
Instead, I recommend starting by documenting the key behaviour of the program, describing its model of the world and defining terminology, and only then trying to document each function in terms of that model and terminology.
That is, the first duty of technical documentation is to be complete and correct (at least for practical purposes). Once you've got that far it's time to pay attention to optimising it for the needs of your likely readers.
Can you explain in more detail how that's different from the approach described in "What nobody tells you about documentation"? [0] At first blush, your recommendation sounds pretty similar to what is suggested in that post.
Is this a critique of the guideline to "Give reference documentation the same structure as the codebase" that was in [0], or is it more like you think the importance of the "Explanation" section is underrated?
(This is coming purely from the perspective of somebody who is trying to write better documentation. I'm not trying to defend any particular stance, just interested in your opinion.)
[0]: https://www.divio.com/blog/documentation/
One is:
- A: a list of functions or similar items, vs
- B: a description of a model, its operations, and terminology
The other is
- X: "the only job is to describe, as clearly and completely as possible", vs
- Y: "a chance to relax and step back"
My reading of the "what nobody tells you" article is that it envisages a reference which is A and X, and an explanation which is B and Y.
I recommend that the reference should be A, B, and X. Having an explanation which is B and Y is a fine thing too.
So basically the bit I don't like in that article is where it says the reference should not attempt to explain basic concepts. Maybe it doesn't need to try to teach concepts, but it very often does need to define them.
(Also, I think rationale fits well in the "describe as clearly and completely as possible" document, especially if you're in a position to separate it a bit from the main text.)
See also this previous comment of mine about a common pitfall of reference documentation: https://news.ycombinator.com/item?id=20473713
The more systematic approach which I've really caught onto recently is to assume it has to be atomized a bit to get any breathing room. Make distinct spaces for the narratives, spaces for basic concepts and references, spaces for formal overviews, and spaces for single tasks, features and APIs. Then have them link to each other, using the link as the leverage to let each part of the documents use the necessary vocabulary without overexplaining. While it's possible to overdo that and produce documentation that is a thicket of links, just clarifying that you have a distinct purpose to the space makes the writing process much more systematic - no confusion over what the writing needs to concentrate on.
Every major system for converting function documentation to code has a slot for documentation at the top of the module/package/class/whatever. I find this is very underused, almost across the board. I actually quite like automatic documentation, on the provision that you put something decent at the top for people to orient with.
1) "negative space": tell people also "what it's not" to avoid misconceptions
2) keeping documentation updated with code
discuss! :)
Listen to our President Donald Trump demand a $4 billion dollar bribe from child rapists to "turn a blind eye" on January 3rd, 2019.
Download the video, turn the volume all the way up and put head phones on. Trump is on a call from with Henry Porter and Gigi Hadid. (See Page 63) Bribe demand at 1018am:
https://drive.google.com/file/d/1Grdr8xF2psKNsuYlEnl9dIRV-77...
This is the tip of the iceberg. PDF link below:
Full 84 page document [updated 22Oct]: FBI_FinalDraft_26Jul2019_BSchlenker.pdf
https://drive.google.com/file/d/1Sj9EN_pHmicKS6rFQlmk67knMdJ...
You might want to save this post. It will be censored when this account logs off.
Listen to Speaker of the House, Senator Nancy Pelosi, accept a $3 billion dollar bribe from wealthy high profile child rapists for safe passage to get Asian boys through the border at "Monterrey" on January 17, 2019.
Download the video, turn the volume all the way up and put head phones on. Call starts at 10:31am.
17JanCh3_949-1100.avi
https://drive.google.com/file/d/1eodHu4o5Cm3xEWhDqipSuTj-M1C...
Excerpts of the dialogue:
Speaker of the House Nancy Pelosi returns to the Porter camera system at 1031 for a check-in. "Nancy Pelosi is here and she wants $3 billion to keep the border open at Monterrey. $3 billion dollars to keep that shit open do you believe that?" Matthew Porter commentates. Pelosi states 1034: "I think he [Brian Schlenker] needs to be removed. I think we need to get this guy out of here". Speaker Pelosi then agrees to call back at 7pm PST. Gigi Hadid at 1034: "Thanks for calling us. I've got you down for three minutes". Pelosi don't worry about that I've got 3 billion.
1031 Matthew Porter: Nancy Pelosi is on and she wants $3 billion dollars to keep the border open at Monterrey. Three billion dollars to keep that shit open do you believe that?
1033 Nancy Pelosi: I don't think that will be necessary unless you insist.
1033 Donald Reeves?: We insist.
1033 Nancy Pelosi: Ok then I guess we have a deal.
1033 Matthew Porter: Thank you Mrs. Pelosi.
1033 Nancy Pelosi: Please call me Speaker Pelosi.
1033 Nancy Pelosi: We want to make sure you have safe passage at Monterrey.
1033 Matthew Porter: We appreciate that Speaker Pelosi.
1033 Gigi Hadid: I think we may have to scale back a little bit though.
1033 Nancy Pelosi: Gigi I think we'll be just fine.
1035 Nancy Pelosi: God damn it! I want Kamala to get a billion out of yours, not out of mine.
1035 Gigi Hadid: I think we can accommodate you but we need to find out if Monterrey will be open on the 30th of January.
1036 Nancy Pelosi: Of course it will Gigi.
1036 Nancy Pelosi: $3 billion goes a long way Peter.
1036 Peter Thiel: Excellent answer.
1043 Gigi Hadid: I think we need to give Kamala a billion dollars to keep her [happy].
1043 Matthew Porter: I think we can do that but we need to get her to do something first.
1043 Gigi Hadid: She did. We got her fucking Rahm Emmanuel Monday morning [14Jan] at 235.
1043 Matthew Porter: Perfect, then we're all set. Send her the billion.
1043? Nancy Pelosi: She'll accept the money, I guarantee it.
1043? Gigi Hadid: Nancy thank you for everything.
<ch4>
1036 Donald Reeves: Don't listen to her. She will close down the border if it's not there. Make sure she gets the $3 billion.
This is the tip of the...
[1] https://web.dev/handbook/quality/
[2] https://web.dev/handbook/content-checklist/
This starts right from the first sentences describing the tool. I am a particular fan of people who don’t hide the purpose of the tool behind several lines of adjectives and credits. The Redis description in the article is exemplary, IMHO.