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.
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.
> "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 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.
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?
What do you call a wiki coupled to a permissions system? That is, a CMS where:
- every logged-in user is a contributor+editor+publisher and so can just edit-and-post content as if the system was a wiki,
- but new users have to be created by some administator, or invited, etc; there's no "Register" link,
- and for non-logged-in users, there are no trappings of "wikidom" visible (e.g. recent changes page, sandbox, any revision of posts other than the marked-as-last-known-good revision, etc.)
I have a feeling that this is what 90% of documentation projects really want: something that's a wiki from the inside, and a CMS from the outside. Does this design have a name?
You can customize wikis to make them into MMO games, but then they're not wikis any more. It would be useful to have a name, I think, for this specific thing, because then people who want this specific thing could download software that already provides this specific thing, with no customization involved.
> You can customize wikis to make them into MMO games, but then they're not wikis any more.
That's not necessarily true. I think it'd be interesting to make a religion-inspired MMO game that's about writing and rewriting a holy text. Use a voting system to make something sacrosanct and thus harder to make changes to.
Sorry for the late reply. Thanks for the offer. It was an internal Wiki for my department at a small college. I used it to distribute lecture notes and things to students, and share other resources with other faculty. I also created a space for students to use it for their projects. It is defunct now. I got too busy last year to keep up with it, and haven't replaced it.
This. The term "wiki" really just means quickly/easily editable (hyper)text. It's a shame it's sort of grown to mean "text that will magically maintain itself". Just like "just open source it" isn't a solution to library maintenance (but can be a prerequisite for community contribution) - "put up a wiki" doesn't mean the thing will curate itself.
I'm reminded of a quote by Cunningham where he says that his most frequent actions on wikis are to delete and consolidate content.
Maintaining a wiki takes work. Having an editor, along with a process for going over material regularly (say once a month) helps a lot. That and/or have "owners" for pages and sections (eg: the developer responsible for the gizmorenderer gets reminders to review the example code and documentation for the renderer, while the devops lead gets reminders to review the install/setup instructions etc). If a section hasn't been marked "good" for the past two-three months - have the system delete it.
Encourage people to review old documentation/pages when writing new -- maybe update a few old examples and add new ones, rather than just add a single new example that covers the new API etc.
Tooling and automatic reminders can help, but at the core what is needed is a (business) process for maintaining the thing -- it can be completely manual -- but it needs to be there.
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"
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."
"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.
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.
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.
> 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.
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.
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.
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.
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.
> 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.
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.
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.
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.
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.
"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.
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.
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.)
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.
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)
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.
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.)
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.)
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.