7 ms·

Teach, Don't Tell

203 points by stevelosh 13y ago

cousin_it 13y ago
The most important thing I want from API documentation is that every method should have a minimal working code example. Minimal - the example should be focused on demonstrating how to call that specific method, with as little other code as possible. That way I don't have to puzzle which parts are essential and which are arbitrary. Working - if I paste the example code into a separate file and run it, it should work. Surprisingly many attempts at documentation fail this test. When we're faced with an unfamiliar problem and an unfamiliar API that can solve that problem, the quickest way of programming is copy-paste programming. The documentation should make copy-paste programming as easy as possible. Understanding comes after imitation.
- 14113 13y ago
  Also, if there is some common code between the examples, include this near the start as scaffolding for the examples. This way the examples are leaner, yet still runnable.
- roopeshv 13y ago
  I think this is a wonderful class for someone starting out and a good outline for people who want to get into practice of doing systematic design. https://class.coursera.org/programdesign-001/class https://class.coursera.org/programdesign-001/class
scoofy 13y ago
I cannot be the only one that felt the titles of the subsections popping up on the left side were entirely redundant and very distracting.
- holyjaw 13y ago
  Quite the opposite - I've always wanted to replicate that part of his site.
- awj 13y ago
  I think it could have waited just a bit so that the title only shows up on the side after you've scrolled entirely past the main one, but beyond that I don't mind it. It's not necessary, but it is marginally useful and not actively annoying. As gratuitous bits of UI go that puts it in the 95 percentile.
- calinet6 13y ago
  A slight sacrifice of extreme utilitarianism for a subtle beauty... I'll allow it.
Mithaldu 13y ago
I wish the text wasn't italic, so it would be easier to read on machines without antialiasing enabled.
- 6d0debc071 13y ago
  It's all text, you can copy paste it into notepad or something. Or just override the styling on the page.
- mhb 13y ago
  There's always Readability: http://www.readability.com/ http://www.readability.com/
- derefr 13y ago
  I would say that there are few enough "machines without antialiasing enabled" that you, not the author, should probably be the one worrying about solving the problem (with a user stylesheet, say.)
mathattack 13y ago
It's a very important topic, but I have to admit the sequencing threw me for a loop. If every tech documentation that I read started with, "Before you read this post there are two other things I think you should read first" I think I'd never have the patience for an answer. Better to start with, "Here's what is important to know, if you want to understand more context, read X and Y"
- derefr 13y ago
  I read the sequencing more as "the most important thing to know, is the thing I didn't write. Read that. If you never make it back here, that's okay, this is just errata compared to that."
6d0debc071 13y ago
One tip I'd give for writing docs is to get Dragon Naturally Speaking and a really good microphone. It's saved me countless hours over the last couple of years (but only because I stopped counting once I reached 500.)
calinet6 13y ago
Fw: AngularJS team... honestly.
abhididdigi 13y ago
Seriously, I LOVE this post. I see all those kinds of documentations on Github, and being fairly new to programming Python, I see it extremely irritating if the documentation is bad and broken. The author just expressed(with words) what I couldn't.
peter_l_downs 13y ago
> When you release a new programming language or library into the wild, > the initial state of your “users” is going to be blank. > The things they need to know when they encounter your library are: > > 1. What is this thing? > 2. Why would I care about this thing? > 3. Is it worth the effort to learn this thing? Yes, please! If all libraries / frameworks included this information it would make everyone's lives so much easier.
fohlin 13y ago
"You teach them." Well, no. You set up a framework of information and activities which allows the individual to learn. It could be beneficial to adopt this view, prominent in education, for software documentation as well. (The article seems to agree, but it is useful to have you language reflect the student as the active party.) We could actually look educational strategies such as constructive alignment [1] here: define the measurable learning outcomes, and provide activities aligned with those outcomes. The tutorial comes to mind as a potentially successful component of documentation. Executed well, it gives at a glance information, while simultaneously providing natural entry points for hands on activity. Add more options for self-assessment and soon you will have a very pedagogically sound learning instrument. [1]: http://en.wikipedia.org/wiki/Constructive_alignment http://en.wikipedia.org/wiki/Constructive_alignment
sirsar 13y ago
>Seriously: fuck wikis. They are bad and terrible. Personally I think the Arch Linux wiki does a fairly good job. I refer to it when setting up other Linux distros.
- caw 13y ago
  I haven't checked out Arch's wiki, but the FreeBSD handbook is a similar thing. It's so well documented I use it to compensate for other documentation.
- yk 13y ago
  Depends, the Arch wiki is great, there is/was the German ubuntuusers.de wiki and of course Wikipedia, but none of these are designed to teach you the basics, they are references. By contrast, for tutorials the state of wikis is quite often tutorial 1-3 is great and the rest just missing.
- NoodleIncident 13y ago
  It was a happy day the first time an Arch Wiki link popped up in my Linux Mint google results. That site is crazy good at documenting edge cases and possible bugs.
- 14113 13y ago
  The arch wiki is absolutely incredible. I don't know how they've got it so good, but for a reference of all the things that can be layered upon linux it's amazing.
7402 13y ago
"The purpose of technical documentation is ... teach them to be an expert user of it" But maybe I don't WANT to be an expert user! Maybe I just want to USE the damn thing. It's frustrating when a tool maker thinks that their tool so important that every user must become an expert on every facet of the tool. How about, "The purpose of technical documentation is to teach the user whatever is necessary and sufficient for their particular needs." I'm a programmer. A few times a year I need to use Photoshop for something Really Simple. I want documentation that can tell me how to draw a rounded rectangle with a shaded gradient inside it (or whatever) as quickly as possible, and tells me as little as possible about anything that doesn't help do that.
- solistice 13y ago
  Doesn't Stack-anything fill that niche already, along with a multitude of youtube videos and online tutorials that will walk you through the most common use cases, especially for software like photoshop? In case that's an actual question, make a rectangular selection and check the "rounded corners" box at the top left. Select the gradient tool (You can see it by clicking the little paintbucked on the left toolbar for a while, it looks like a gradient). Klick somewhere and drag with the tool selected. And there's your rounded rectange with a shaded gradient inside.
  - ksmiley 13y ago
    > Doesn't Stack-anything fill that niche already? If you ask, "how do I use [library X] to draw a rounded rectangle?" on Stack Overflow, they will put your question on hold until you show code that demonstrates that you tried. This may be difficult for someone who has only just succeeded in getting the library to compile! To continue the author's car analogy, Ms. Smith sits in the passenger seat while you try to drive to grandpa's house. When you fail to reach your destination and give up, Ms. Smith will tell you what you did wrong. But only if you made a non-trivial effort. If you ram into the living room while trying to exit the driveway, you'll only get a disapproving glare.
simonsarris 13y ago
I've tried to adhere to something similar to this for as long as I've written a library, and one of the great things about writing JavaScript libraries is that you can execute tutorials with live code execution inside the documentation itself. I wouldn't call it teaching per se, more of a framework for self-learning, especially for users who learn by example. I'd stick with the older saying "Show, Don't Tell," while making sure they can copy what you've shown. I think this is a simpler rubric: There should be at least two parts to documentation, API and Introduction pages. The introduction pages start off with a "First Contact" page and then delve into the myriad topics of the library (with a "Hairball" table of contents to explore if they please). These topics that may not all be relevant to a particular user, and ought to be as independent as possible. Ideally users should not be expected to read many pages before making sense of any other page. The API must contain definitions for every method and property, but should also make clear what the purpose of any particular class is and give a short explanation of common usage. The API should then link to the introduction so that common example code can be seen in action. Both the API and the introduction pages reference each-other constantly. For example in my library the Panels API page[1] contains several paragraphs outlining the purpose and common layout options of Panels, as well as (importantly!) linking to the associated introduction pages[2], where a user can see running code examples of common Panels, with code they can directly copy/paste into their own page to achieve identical panel layouts. The result should be something tightly coupled, with many links back and forth between introduction pages and the API, but the end result is not an actual wiki. I can understand the author's hatred of wiki's, because for most projects setting up a wiki is a lot like shifting responsibility for creating documentation to nobody. Which means it never gets done. (At for most projects I've seen and I think the author would agree. I'm sure there are a few great library wikis out there with nontrivial user-sourced content.) [1] Panels API page: http://gojs.net/beta/api/symbols/Panel.html http://gojs.net/beta/api/symbols/Panel.html [2] Panels "Intro" page: http://gojs.net/beta/intro/panels.html http://gojs.net/beta/intro/panels.html Compare these with, say, the Google Maps API page for "Map": https://developers.google.com/maps/documentation/javascript/reference#Map https://developers.google.com/maps/documentation/javascript/... Or worse, MVCArray: https://developers.google.com/maps/documentation/javascript/reference#MVCArray https://developers.google.com/maps/documentation/javascript/... There's extremely little about what it is, what is expected of it, and common uses of it. ~~~ If you write a JavaScript library, there is no excuse for not having live code examples and tutorials tightly coupled as part of the documentation.
prlin 13y ago
slightly OT but any suggestions on a better keyboard? I'm doing fine with my current one but I'd like to know what I'm missing out on.
- bosie 13y ago
  http://www.kinesis-ergo.com/advantage.htm http://www.kinesis-ergo.com/advantage.htm
  - prlin 13y ago
    do you have one? are those actually comfortable?
- holyjaw 13y ago
  From the author: http://stevelosh.com/blog/2012/10/a-modern-space-cadet/ http://stevelosh.com/blog/2012/10/a-modern-space-cadet/ (See the first part about hardware)
  - prlin 13y ago
    thanks. didn't see that post.
mr_luc 13y ago
I agree with this part: > You should have a table of contents that lists each section of the “hairball”. And then each section should have its own table of contents that lists the sections inside it. A table of contents is a wonderful way to get a birds-eye view of what you’re about to read, to prepare your brain for it. And of course it’s also handy for navigating around. I think that in the case of the article, that table of contents could have been pinned on the left-hand side, instead of using that space for a cool-for-a-few-seconds effect.
zdw 13y ago
> "Seriously: fuck wikis. They are bad and terrible. Do not use them. Take the time and effort to write some real documentation instead." I simultaneously agree and disagree with this. Wikis fall into two categorys: 1. "If I build it, they will come", which is where the developer who doesn't want to write docs throws one up, and says "hey, all you users, document it on your own, I don't want to mess with it". Then new versions come out, things change, the docs are old/incorrect, and people get frustrated, and nobody end's up using the wiki. 2. People who actually take time to make it into a great site - these are few and far between. http://ipxe.org http://ipxe.org is one example of a well done wiki, but I'm betting that a single person spent a good deal of time doing the site. Unfortunately, it appears that 95% of the technical documentation wikis out there are in group #1, not group #2.
- solistice 13y ago
  But if it's just one person maintaining the wiki, with a few others contributing, why have a wiki at all instead of a centrally curated guide? With wiki like systems, you get noise (in the form of people making mistaken changes, malicious changes, etc.). There's really only two ways you can guarantee quality, which is either the aforementioned person reversing those changes (undoubtedly additional work), or enough people checking those edits, improving or reverting them. But your small to medium size project isn't going to garner enough people to have the latter option work well. And if you have a small group of people that would be willing to do that maintenance work, why not just write some documentation together with them?
  - fnordfnordfnord 13y ago
    I cultivated a wiki for a few years in the hope that someone would come.
    - solistice 13y ago
      If it will make you feel better, you could tell me the link and I'll check it out.
solistice 13y ago
I feel the authors pain, both from trying to learn frameworks with missing documentation ("I want to use this function, but there aren't even comments on it :D"), and having a father who once told me I was retarded for being unable to convert hex to binary in my head. I was ten. I agree with the authors main points, but I'm kinda vexed by him trying to label it documentation. Technically, what he's proposing people to write is guides, not just documentation. If I write a piece of code, and I explain what it does, then that's documenting it, and the result is documentation. If I show you in writing how to use it, I guide you. It's a guide. So is a guide documentation? You could classify it like that, but i think that will be a source of confusion. A better term encompassing both guides and documentation would be supplemental documents, encompassing everything that is not code. So we get code supplemental documents -guides -documentation --comments --reference manuals Or something like that. I'm really just being finicky, but I like categorizing things.
swamp40 13y ago
Of course, son. The car is in the garage and I laid out a set of wrenches on the workbench. Take the car apart and look at each piece, then put it back together. Once you’ve done that I’ll take you to the DMV for your driving test. Reminds me of the story of young Walter Chrysler and his Locomobile. Edit: For those interested, it's a quick one page read, starting at the bottom paragraph of page 5: http://www.chryslergroupllc.com/company/Heritage/Heritage%20Documents/Chrysler%20Heritage%201900/Chrysler%20History%20-%20Walter%20P.%20Chrysler.pdf http://www.chryslergroupllc.com/company/Heritage/Heritage%20...
twosinxcosx 13y ago
I actually want to try writing technical docs, but I can't seem to find a beginner friendly project/framework that I can pick up a small task and work on it. Do you have any suggestions? Shall I try approaching people in Mozilla etc where they always have some work or wait until I find a project that I personally use and lacks some docs so I can try working on it individually? I would rather have some kind of mentorship but I do not think people will invest time in a random person over the internet.
singingfish 13y ago
I wrote a web programming book three years ago (moderately successful, made back its advance, and got me the career change I was looking for) using a philosophy that has a very similar approach to this. My approach is: 1. All code examples must lead to a working program, or can be easily integrated into a working program. Preferably the program has trivial functionality. Conceptual material must relate back to a working example. 2. Avoid applying excessive cognitive load to the readers. Human short term memory has a capacity of 7±2 items. Your material must be pitched at a level where there is a maximum of five concepts in play at any one time (five being the maximum "guaranteed" short term memory for a healthy adult). This is much easier to acheive with goal 1 as it the approach guides the writer as to which item needs to be explained next. From that perspective, unix man pages drive me nuts. Learning to read man pages is one of the core skills that needs to be developed in order to become an effective user of unix like systems.
- singingfish 13y ago
  the idea of 'five concepts' is interesting as it's related to the level you're pitching at. The idea is that you get people up and running with the initial working code, and if they manage that, then they can follow what you're doing subsequently, and you can keep a feel of their levels of consolidated knowledge.
RWeaver 13y ago
I wish I could upvote this a thousand times. It's great documentation, about documentation. I wonder if it would be worth encouraging people to put their names on official documentation that they write. They'll take some pride in it, and get some benefit in that they're recognized as an expert, and everyone else gets a whole bunch more well written documentation (hopefully)

203 points by stevelosh 13y ago

The most important thing I want from API documentation is that every method should have a minimal working code example. Minimal - the example should be focused on demonstrating how to call that specific method, with as little other code as possible. That way I don't have to puzzle which parts are essential and which are arbitrary. Working - if I paste the example code into a separate file and run it, it should work. Surprisingly many attempts at documentation fail this test. When we're faced with an unfamiliar problem and an unfamiliar API that can solve that problem, the quickest way of programming is copy-paste programming. The documentation should make copy-paste programming as easy as possible. Understanding comes after imitation.

14113 13y ago
Also, if there is some common code between the examples, include this near the start as scaffolding for the examples. This way the examples are leaner, yet still runnable.
roopeshv 13y ago
I think this is a wonderful class for someone starting out and a good outline for people who want to get into practice of doing systematic design. https://class.coursera.org/programdesign-001/class https://class.coursera.org/programdesign-001/class

scoofy 13y ago

I cannot be the only one that felt the titles of the subsections popping up on the left side were entirely redundant and very distracting.

holyjaw 13y ago
Quite the opposite - I've always wanted to replicate that part of his site.
awj 13y ago
I think it could have waited just a bit so that the title only shows up on the side after you've scrolled entirely past the main one, but beyond that I don't mind it. It's not necessary, but it is marginally useful and not actively annoying. As gratuitous bits of UI go that puts it in the 95 percentile.
calinet6 13y ago
A slight sacrifice of extreme utilitarianism for a subtle beauty... I'll allow it.

Mithaldu 13y ago

I wish the text wasn't italic, so it would be easier to read on machines without antialiasing enabled.

6d0debc071 13y ago
It's all text, you can copy paste it into notepad or something. Or just override the styling on the page.
mhb 13y ago
There's always Readability: http://www.readability.com/ http://www.readability.com/
derefr 13y ago
I would say that there are few enough "machines without antialiasing enabled" that you, not the author, should probably be the one worrying about solving the problem (with a user stylesheet, say.)

mathattack 13y ago

It's a very important topic, but I have to admit the sequencing threw me for a loop. If every tech documentation that I read started with, "Before you read this post there are two other things I think you should read first" I think I'd never have the patience for an answer. Better to start with, "Here's what is important to know, if you want to understand more context, read X and Y"

derefr 13y ago
I read the sequencing more as "the most important thing to know, is the thing I didn't write. Read that. If you never make it back here, that's okay, this is just errata compared to that."

6d0debc071 13y ago

One tip I'd give for writing docs is to get Dragon Naturally Speaking and a really good microphone. It's saved me countless hours over the last couple of years (but only because I stopped counting once I reached 500.)

calinet6 13y ago

Fw: AngularJS team... honestly.

abhididdigi 13y ago

Seriously, I LOVE this post. I see all those kinds of documentations on Github, and being fairly new to programming Python, I see it extremely irritating if the documentation is bad and broken. The author just expressed(with words) what I couldn't.

peter_l_downs 13y ago

> When you release a new programming language or library into the wild, > the initial state of your “users” is going to be blank. > The things they need to know when they encounter your library are: > > 1. What is this thing? > 2. Why would I care about this thing? > 3. Is it worth the effort to learn this thing? Yes, please! If all libraries / frameworks included this information it would make everyone's lives so much easier.

fohlin 13y ago

"You teach them." Well, no. You set up a framework of information and activities which allows the individual to learn. It could be beneficial to adopt this view, prominent in education, for software documentation as well. (The article seems to agree, but it is useful to have you language reflect the student as the active party.) We could actually look educational strategies such as constructive alignment [1] here: define the measurable learning outcomes, and provide activities aligned with those outcomes. The tutorial comes to mind as a potentially successful component of documentation. Executed well, it gives at a glance information, while simultaneously providing natural entry points for hands on activity. Add more options for self-assessment and soon you will have a very pedagogically sound learning instrument. [1]: http://en.wikipedia.org/wiki/Constructive_alignment http://en.wikipedia.org/wiki/Constructive_alignment

sirsar 13y ago

>Seriously: fuck wikis. They are bad and terrible. Personally I think the Arch Linux wiki does a fairly good job. I refer to it when setting up other Linux distros.

caw 13y ago
I haven't checked out Arch's wiki, but the FreeBSD handbook is a similar thing. It's so well documented I use it to compensate for other documentation.
yk 13y ago
Depends, the Arch wiki is great, there is/was the German ubuntuusers.de wiki and of course Wikipedia, but none of these are designed to teach you the basics, they are references. By contrast, for tutorials the state of wikis is quite often tutorial 1-3 is great and the rest just missing.
NoodleIncident 13y ago
It was a happy day the first time an Arch Wiki link popped up in my Linux Mint google results. That site is crazy good at documenting edge cases and possible bugs.
14113 13y ago
The arch wiki is absolutely incredible. I don't know how they've got it so good, but for a reference of all the things that can be layered upon linux it's amazing.

7402 13y ago

"The purpose of technical documentation is ... teach them to be an expert user of it" But maybe I don't WANT to be an expert user! Maybe I just want to USE the damn thing. It's frustrating when a tool maker thinks that their tool so important that every user must become an expert on every facet of the tool. How about, "The purpose of technical documentation is to teach the user whatever is necessary and sufficient for their particular needs." I'm a programmer. A few times a year I need to use Photoshop for something Really Simple. I want documentation that can tell me how to draw a rounded rectangle with a shaded gradient inside it (or whatever) as quickly as possible, and tells me as little as possible about anything that doesn't help do that.

solistice 13y ago
Doesn't Stack-anything fill that niche already, along with a multitude of youtube videos and online tutorials that will walk you through the most common use cases, especially for software like photoshop? In case that's an actual question, make a rectangular selection and check the "rounded corners" box at the top left. Select the gradient tool (You can see it by clicking the little paintbucked on the left toolbar for a while, it looks like a gradient). Klick somewhere and drag with the tool selected. And there's your rounded rectange with a shaded gradient inside.
- ksmiley 13y ago
  > Doesn't Stack-anything fill that niche already? If you ask, "how do I use [library X] to draw a rounded rectangle?" on Stack Overflow, they will put your question on hold until you show code that demonstrates that you tried. This may be difficult for someone who has only just succeeded in getting the library to compile! To continue the author's car analogy, Ms. Smith sits in the passenger seat while you try to drive to grandpa's house. When you fail to reach your destination and give up, Ms. Smith will tell you what you did wrong. But only if you made a non-trivial effort. If you ram into the living room while trying to exit the driveway, you'll only get a disapproving glare.

simonsarris 13y ago

I've tried to adhere to something similar to this for as long as I've written a library, and one of the great things about writing JavaScript libraries is that you can execute tutorials with live code execution inside the documentation itself. I wouldn't call it teaching per se, more of a framework for self-learning, especially for users who learn by example. I'd stick with the older saying "Show, Don't Tell," while making sure they can copy what you've shown. I think this is a simpler rubric: There should be at least two parts to documentation, API and Introduction pages. The introduction pages start off with a "First Contact" page and then delve into the myriad topics of the library (with a "Hairball" table of contents to explore if they please). These topics that may not all be relevant to a particular user, and ought to be as independent as possible. Ideally users should not be expected to read many pages before making sense of any other page. The API must contain definitions for every method and property, but should also make clear what the purpose of any particular class is and give a short explanation of common usage. The API should then link to the introduction so that common example code can be seen in action. Both the API and the introduction pages reference each-other constantly. For example in my library the Panels API page[1] contains several paragraphs outlining the purpose and common layout options of Panels, as well as (importantly!) linking to the associated introduction pages[2], where a user can see running code examples of common Panels, with code they can directly copy/paste into their own page to achieve identical panel layouts. The result should be something tightly coupled, with many links back and forth between introduction pages and the API, but the end result is not an actual wiki. I can understand the author's hatred of wiki's, because for most projects setting up a wiki is a lot like shifting responsibility for creating documentation to nobody. Which means it never gets done. (At for most projects I've seen and I think the author would agree. I'm sure there are a few great library wikis out there with nontrivial user-sourced content.) [1] Panels API page: http://gojs.net/beta/api/symbols/Panel.html http://gojs.net/beta/api/symbols/Panel.html [2] Panels "Intro" page: http://gojs.net/beta/intro/panels.html http://gojs.net/beta/intro/panels.html Compare these with, say, the Google Maps API page for "Map": https://developers.google.com/maps/documentation/javascript/reference#Map https://developers.google.com/maps/documentation/javascript/... Or worse, MVCArray: https://developers.google.com/maps/documentation/javascript/reference#MVCArray https://developers.google.com/maps/documentation/javascript/... There's extremely little about what it is, what is expected of it, and common uses of it. ~~~ If you write a JavaScript library, there is no excuse for not having live code examples and tutorials tightly coupled as part of the documentation.

prlin 13y ago

slightly OT but any suggestions on a better keyboard? I'm doing fine with my current one but I'd like to know what I'm missing out on.

bosie 13y ago
http://www.kinesis-ergo.com/advantage.htm http://www.kinesis-ergo.com/advantage.htm
- prlin 13y ago
  do you have one? are those actually comfortable?
holyjaw 13y ago
From the author: http://stevelosh.com/blog/2012/10/a-modern-space-cadet/ http://stevelosh.com/blog/2012/10/a-modern-space-cadet/ (See the first part about hardware)
- prlin 13y ago
  thanks. didn't see that post.

mr_luc 13y ago

I agree with this part: > You should have a table of contents that lists each section of the “hairball”. And then each section should have its own table of contents that lists the sections inside it. A table of contents is a wonderful way to get a birds-eye view of what you’re about to read, to prepare your brain for it. And of course it’s also handy for navigating around. I think that in the case of the article, that table of contents could have been pinned on the left-hand side, instead of using that space for a cool-for-a-few-seconds effect.

zdw 13y ago

> "Seriously: fuck wikis. They are bad and terrible. Do not use them. Take the time and effort to write some real documentation instead." I simultaneously agree and disagree with this. Wikis fall into two categorys: 1. "If I build it, they will come", which is where the developer who doesn't want to write docs throws one up, and says "hey, all you users, document it on your own, I don't want to mess with it". Then new versions come out, things change, the docs are old/incorrect, and people get frustrated, and nobody end's up using the wiki. 2. People who actually take time to make it into a great site - these are few and far between. http://ipxe.org http://ipxe.org is one example of a well done wiki, but I'm betting that a single person spent a good deal of time doing the site. Unfortunately, it appears that 95% of the technical documentation wikis out there are in group #1, not group #2.

solistice 13y ago
But if it's just one person maintaining the wiki, with a few others contributing, why have a wiki at all instead of a centrally curated guide? With wiki like systems, you get noise (in the form of people making mistaken changes, malicious changes, etc.). There's really only two ways you can guarantee quality, which is either the aforementioned person reversing those changes (undoubtedly additional work), or enough people checking those edits, improving or reverting them. But your small to medium size project isn't going to garner enough people to have the latter option work well. And if you have a small group of people that would be willing to do that maintenance work, why not just write some documentation together with them?
- fnordfnordfnord 13y ago
  I cultivated a wiki for a few years in the hope that someone would come.
  - solistice 13y ago
    If it will make you feel better, you could tell me the link and I'll check it out.

solistice 13y ago

I feel the authors pain, both from trying to learn frameworks with missing documentation ("I want to use this function, but there aren't even comments on it :D"), and having a father who once told me I was retarded for being unable to convert hex to binary in my head. I was ten. I agree with the authors main points, but I'm kinda vexed by him trying to label it documentation. Technically, what he's proposing people to write is guides, not just documentation. If I write a piece of code, and I explain what it does, then that's documenting it, and the result is documentation. If I show you in writing how to use it, I guide you. It's a guide. So is a guide documentation? You could classify it like that, but i think that will be a source of confusion. A better term encompassing both guides and documentation would be supplemental documents, encompassing everything that is not code. So we get code supplemental documents -guides -documentation --comments --reference manuals Or something like that. I'm really just being finicky, but I like categorizing things.

swamp40 13y ago

Of course, son. The car is in the garage and I laid out a set of wrenches on the workbench. Take the car apart and look at each piece, then put it back together. Once you’ve done that I’ll take you to the DMV for your driving test. Reminds me of the story of young Walter Chrysler and his Locomobile. Edit: For those interested, it's a quick one page read, starting at the bottom paragraph of page 5: http://www.chryslergroupllc.com/company/Heritage/Heritage%20Documents/Chrysler%20Heritage%201900/Chrysler%20History%20-%20Walter%20P.%20Chrysler.pdf http://www.chryslergroupllc.com/company/Heritage/Heritage%20...

twosinxcosx 13y ago

I actually want to try writing technical docs, but I can't seem to find a beginner friendly project/framework that I can pick up a small task and work on it. Do you have any suggestions? Shall I try approaching people in Mozilla etc where they always have some work or wait until I find a project that I personally use and lacks some docs so I can try working on it individually? I would rather have some kind of mentorship but I do not think people will invest time in a random person over the internet.

singingfish 13y ago

I wrote a web programming book three years ago (moderately successful, made back its advance, and got me the career change I was looking for) using a philosophy that has a very similar approach to this. My approach is: 1. All code examples must lead to a working program, or can be easily integrated into a working program. Preferably the program has trivial functionality. Conceptual material must relate back to a working example. 2. Avoid applying excessive cognitive load to the readers. Human short term memory has a capacity of 7±2 items. Your material must be pitched at a level where there is a maximum of five concepts in play at any one time (five being the maximum "guaranteed" short term memory for a healthy adult). This is much easier to acheive with goal 1 as it the approach guides the writer as to which item needs to be explained next. From that perspective, unix man pages drive me nuts. Learning to read man pages is one of the core skills that needs to be developed in order to become an effective user of unix like systems.

singingfish 13y ago
the idea of 'five concepts' is interesting as it's related to the level you're pitching at. The idea is that you get people up and running with the initial working code, and if they manage that, then they can follow what you're doing subsequently, and you can keep a feel of their levels of consolidated knowledge.

RWeaver 13y ago

I wish I could upvote this a thousand times. It's great documentation, about documentation. I wonder if it would be worth encouraging people to put their names on official documentation that they write. They'll take some pride in it, and get some benefit in that they're recognized as an expert, and everyone else gets a whole bunch more well written documentation (hopefully)