The following is a recording of a presentation about passive versus reactive documentation by Greg Koberger, developer and designer for ReadMe.io, a slick new REST API documentation tool. Greg gave this presentation at the STC Silicon Valley chapter meeting on January 12, 2015 in Santa Clara, California. (He gave a similar presentation to a Write the Docs meetup group in San Francisco.) Length: 76 min. Download MP3 (right-click and select Save As) You can view the slides here. About Greg Koberger Gregory Koberger is the founder of ReadMe.io, which provides collaborative developer hubs for companies or projects. He has previously worked at Mozilla, Greylock, and numerous startups. You can learn more about Greg at gkoberger.net. You can explore ReadMe.io here: [caption id="attachment_22520" align="alignnone" width="550"] ReadMe.io[/caption] Here's my brief summary of the presentation. Overview of doc levels Greg outlined three levels of documentation: Passive: Has no knowledge of the user. Reactive: Responds to an action from the user, such as something the user says or does. Proactive: Anticipates the user's needs and pushes the appropriate content to the user at the right time. Passive Passive documentation is documentation that could be contained inside a book. It is often produced by static site generators, and includes deliverables such as topical guides, tutorials, and reference material. Level 1.5: Passive(ish) example Moving a half a step beyond passive, examples such as forums, Q&A sites like Stack Overflow, and other community driven or collaboratively edited sites aren't totally passive, nor do they have completely static content. With a Q&A post on StackOverflow, for example, users are asking questions and getting responses from other users. (Greg noted that StackOverflow provides a compelling model for documentation. If someone searches for a technical answer and can't find it online, he or she asks the question so that the next time someone searches for the answer, it's available.) Why do docs need to be dynamic? Greg said that when you're building a website, on average a developer uses between 8-10 APIs. As a result, developers need to quickly get in and out of various documentation sites, finding code snippets to easily copy and paste, locating quick answers, etc. When people are traversing so many different APIs, they don't have time to read through tomes of documentation at a leisurely pace. Dynamic docs can help reduce the cognitive load on the user who is quickly looking for answers and code samples. One example is a section on authentication. Nearly every API doc includes this section, with a sample about how to pass your credentials or API token with REST calls. Why not have the user log in to the doc site, and then auto-populate code samples with his or her authentication credentials directly into the code samples dynamically, making it easier for the user to copy and paste the sample? This is one example of how to reduce cognitive load on the user. Level 2: Reactive doc With reactive documentation, you use what you know about your users to make their lives easier. Ideally, code samples and other information should be personalized with information pulled from the user's profile. For example, if you know what platform the user is on (based on profile information), you can dynamically filter the doc content. If the user's preferred language is PHP, your code snippets can default to the PHP tab instead of the Ruby tab, for example. Greg emphasized that code samples should be copy-and-pastable so they just work. Another example with reactive documentation might be an on-boarding tutorial. If you know details about the employee's location, role, and other details, then you can dynamically filter the on-boarding tasks to fit that profile. Error messages are another place to personalize and customize content. The errors themselves can contain variables that are personalized -- for example, instead of "Fa