Permaculture: permanent+agriculture:
- work with the elements
- build a resilient system
- use of protracted and thoughtful observation
- observe/design/evolve
"the edge is where the action is":
- where the fields meet the woods
- where docs meet devs (code samples?)
How to bring docs order to lawless towns. How to come into a company with no docs, or terrible docs, and no culture of good docs.
Assert your right to exist.
Work out who sits where and what they know. Look for any existing docs in any form. Research competitors and users. If there's a feeling that writers don't listen, be an active listener.
No time for frills. Deliver early and often, or explain why you can't.
Address the biggest internal pain points. Give people a structure (e.g. use big tracking).
Look for hoarded docs, or stuff from the last sheriff.
Make sure docs are seen as part of the product. Find peers. Plat (plan, map) your docs.
The best TAs are those who have struggled, because they understand how to work and apply yourself. Lack of internal documentation causes growing pains with hiring and cross-team communications. When she joined as a new dev, took a long time to understand some especially gnarly code, had to have the CTO explain it. Not scalable.
What do do? Rant about this gnarly code and how hard it is to understand! It turns out, that even though her rant was very imperfect:
- it flushed out many other people who had the same confusions
- the act of writing it helped her to understand it
- writing something wrong spurred people who did understand it into fixing it
"get your crappy draft out there now!"
Meeting notes: the garbage truck of docs. How can we make better meeting notes?
- understand your audience: who is reading the notes, and what is important to them?
- disregard chronology: write the most important things first
- engage subject matter experts, and get clarification if you are not clear.
- action items need to be clear.
What techniques can writers steal from developers?
Don't start with a blank page. Use a template for every kind of document. Make a spec for a document, defining the questions you will answer and your audience.
Can we borrow "design patterns" for docs? Possible patterns for docs. For example:
- tell a story
- reference
- picture
- level up
- drill down
No "it", no passive, vague, changing definitions.
Be willing to change structure.
Give a 3rd party company a job to do, to walk through what it's like for real new customers. Real customers file completely different bugs, they file bugs we didn't know about.
- OpenStack ops guide: 3-7 people wrote most of this book, but there was a long tail.
- book sprint: many OpenStack users got together and wrote the book over a weekend
- O'Reilly published it, now there will be a sequel
How can you make docs measurable?
- how many people clicked through a tutorial, and can we correlate that with people who created new repos?
- how many people who accessed the tutorial used that feature?
- consists of HTML, CSS, XML
- portable, searchable, sharable
- PDF is awful, not made for sharing
- to see what's in EPUB, just unzip one.XML is in .opf file (Open Package File), it's a manifest for the book
- idpf.org
Zapier, his company, makes software that can convert one XHR API to another one. A user asked for a new API to be added. It looked tricky, and was not a big market, so Zapier didn't. The user, who's nontechnical, worked it out themselves and implemented it. How?
- had a clear goal in mind
- was motivated
- had open access to tools and docs
- had a support line
How can docs help here?
- make it familiar
- make it easy to get something working ("get paint on the canvas")
- working examples, with overlap between them
- small steps between working versions, so harder to get off in the weeds
- checklists: what you'll need to start this tutorial, what we'll cover in it
- screenshots
- next steps after each example
Different ways to read: skim/flip/read. All are valid. Using graphics in documentation can help. Read Tufte, also http://www.amazon.com/Information-Dashboard-Design-Effective-Communication/dp/0596100167.
- pull quotes to draw attention to a skim-reader
- use of titles and subtitles
- use of colour
-> Symbolicons
Conceptual tools, which we could emphasize with graphics:
- good/bad
- problem/solution
- before/after
- good/better/best
- compare/contrast
- analogy
- timeline
MVP: tests the feasibility of an idea. Crosses the gap between early adopters (minimal) and mainstream users (viable). But, early adopters don't always adopt, and don't always give useful feedback.
How can people use your interface if they don't understand its iconography/abstractions? This requires empathy, which developers are not always good at. But writers are, or should be, better.
Who are your users, and what do they want to do? How-to documents are key to learning, not only in software. Forget what it's like to be an expert user. How-to docs can also help with regressions as a form of test: they express how an interface is supposed to work. They can also act as a test of poor UX: when a how-to gets too long or complex this might signal product problems.
What about docs-first development? What if you prototyped the user's experience in words first?
Kenneth Reitz wrote the Python requests module among many other things. Also maintains The Hitchhiker’s Guide to Python, which uses Git/GitHub + read the docs to create and maintain a full length book written by 135 contributors. His talk was about how this kind of approach to documentation represents a revolution in communication, enabling an "many to many" model where many writers can communicate with many readers.
Rules to simplify writing:
- Write positive statements.
- Write short sentences.
- Use one topic per sentence.
- Use valid nomenclature.
- Write simple sentences.
- Use the active voice.
- Do not use gerunds (-ing words).
- Avoid conditional tenses.
- Avoid word clusters.
- Use valid nomenclature & abbreviations.
(https://en.wikipedia.org/wiki/Simplified_Technical_English)
This talk was incomprehensible, but had some interesting references:
- "Madame Documentation" (Suzanne Briet - one of the first female librarians at the Bibliotheque Nationale)
We have become confused by the difference between presentations and documentation. As a result presentations are awful because they try to be documentation. We need to be clear about the differences:
- documentation is self-guided and meant to be read
- presentations are presenter-guided and meant to be heard/watched.
People worry, though:
This is your problem not your audience's. Try making the presentation like a story, it will be easier to remember.
See An Introvert’s Guide to Better Presentations. Good slides aren't made to be shared, they're meant to be presented.
If the data to be delivered is independent of the deliverer, then it should be a document.
When we treat presentations like documentation, we get bad presentations and bad docs. Amazon and LinkedIn have abolished presentations in meetings: they spend the first 10 minutes of a meeting in silence reading the document to be discussed, then discuss it.
Programmers hate documentation: "I don't ever read the docs". We don't treat docs like we do SW. We don't test it or maintain it in the same way. We're numb to docs, and don't expect people to RTFM. Broken window theory.
We should always require code and tests and docs for a fix.
Things to hate:
- content-free auto-generated docs
- overly verbose docs. Know your audience: you may need the extra stuff or mat not. SSH has 4 levels of verbosity you can choose from: should we have verbosity levels for docs?
Noise is sound without structure. Music is sound with structure. Everyone can tell the difference.
Docs can be music or noise. It can have theme, harmony, tempo - or not. Even if it has the necessary info, it can be noise. It's not as easy to discern musicality with docs as with sound, but it's still there and still matters.
Think of deliberate noise in docs, e.g. the itunes agreement, which asks you to declare "I have read and agreed to these terms", but it is 29 pages of unreadable text. It is not designed to be read but to produce acquiescence.
"a musical document succeeds by satisfying the brain's innate needs". Ask yourself: did you enjoy reading this doc? Did you find it satisfying?
Brian works on Adroll: complex, realtime system, tightly couple to external systems. Humans are bad at predicting the behavior of complex systems. We write docs to try to understand it, but communicating about them is hard too, and mistakes can be disastrous.
Instrumentation reflects the current reality of the system. It's possible to have too much or too little, or badly-presented, instrumentation. So we also write docs, to help interpret it. So instrumentation helps address the problems of documentation, and vice versa.
Works at Puppet Labs. Worked on an advanced guide to modules. The first draft had some problems:
- orientation was a challenge: the doc was overwhelming. Solution: added headings and intro paragraphs as signposts
- navigation: it was hard to locate items. The doc was "readable but not usable". Solution: break it down into step by step guides, with examples. Make it less high level, more dirty details.
Working on docs for Google's cloud services. What's the experience like for first-timers looking at your product documentation?
- what happens when you search for your tech? what logo appears, what listings? how many clicks to the "Getting Started" guide?
- try finding your own content. Understand where users can coming from (use Google Analytics, for example)
The stages of first-user experience:
- finding something useful
- getting something, anything, working
- getting their thing working
Their initial getting started took 24 steps. Too many. They conducted user research, asking questions like: how are we doing? what tools are you using? where are your pain points? The result was that there are a lot of information but not much how-to: "a big pantry with no recipes".
Principles:
- user is in control
- give them what they want, quickly
- reduce friction
- show, don't tell
Dropped "Time to Hello World" metric to 15 minutes. Then wrote a widget enabling users to generate "Hello World" in just 30 seconds.
Understand and share your users' needs. Use your own API, use other APIs and read their docs. Know who your readers are. Make sure you know! Ask them. Ask them what they want. They did, and found they wanted (1) code samples and (2) written docs.
Tell true stories. Provide a good UI: single-page docs with excellent typography. Document edge cases in detail.
Wanted to developer documentation like a product. Static site generator let them build docs from source. Use Markdown+Git+GitHub. Use GitHub issues for tracking docs bugs. Anyone who contributes to the project can contribute to the docs using the same tools. Is it hard to use? No harder than learning a standard CMS.