Teach, Don't Tell

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.

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 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.

Better to start with, "Here's what is important to know, if you want to understand more context, read X and Y"

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.

    > 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?

    >Seriously: fuck wikis. They are bad and terrible.

> 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.

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.

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.

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

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%20...

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.

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)

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

[2] Panels "Intro" page: 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/...

Or worse, 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.