[Note: Giant conference notes info-dump behind the link. These are raw notes, I’ve not really cleaned them up at all, but wanted to share in case others find it useful.]

Putting the (Docs) Cart Before the (Standards) Horse – Drew Jaynes

Drew works for 10Up, and runs docs for WordPress.org.

Discussing how we took 10 years of documents and created a standard from it.

Why and how we developed a standard.

Back Story

• Very little attention was given to the “details” of inline docs
• 10+ years of loosely following phpDoc 1.0
• Codex (wiki) somehow still seen as the main entry point for all developers and users.

What the what?

• Source docs were second class.

The Codex

• 2300+ page manually curated wiki
• Pre-release master list
• Codex sprints
• Needing something better, was becoming unsustainable as our release cycle sped up

Hook Docs

• Tasked with documenting all hooks in core
• Set to go where no documentarian had gone before
• Needed a precedent driven standard as a guide
• Expected an influx of docs and contributors

This lead to developing a full inline-documentation standard.

Rewind

• Evolution of the “Docs Team”
• Established ourselves as a contributor group
• Codex Survey — surveyed usage of the codex, which was used to create a roadmap.
• Informal summit at Open Help Conference

Roadmap

Never underestimate the power of a docs team with a roadmap.

• Work began on a parser and code reference theme
• 1.0 of the inline docs standard was adopted
• Hook documentation began in earnest

Docs Team Evolved

• 3-5 sub-teams working simultaneously based on the roadmap
• Weekly chats
• Weekend virtual sprints
• Collaboration with other teams has raised our profile

Where are we now?

• 48% increase in inline docs over last 3 releases
• All hooks (2200+) documented
• 40 new contributors (over 3 releases)
• v1.0 of the Code Reference is live

It’s not that we weren’t writing inline documentation before, it’s that no one was paying attention, so it’d be incomplete almost to the point of being useless.

Takeaways

• Developing a standard proved quite beneficial
• Redirect to hubs (developer, user, support)
• Standard allowed for longer-term consistency (new inline-doc standard isn’t a major deviation from existing practices, so it’s not a large hurdle).
• Brought the docs team to a more equal footing
• Codex is being supplanted in a way that remains up to date more easily. “Eventually Codex will be one massive 301 redirect.”

http://make.wordpress.org/docs

Q&A: What sort of response from devs when you say “Not having docs is a bug.”

Honestly, it’s been a pretty positive response. It helps that I’m already a core contributor and they know me. Also, I’m always paying attention, and so it consistently gets caught. It helped to establish it as part of our coding practices.

Q&A: Is it also part of your “definition of done”?

Absolutely. Docs get parsed once a day, same time as our nightlies.

Q&A: Do you have thoughts about the difference between manual vs generated docs.

One of our worries in going from curated to parsed was that we’d end up with something actually LESS useful. We built in tools to the parser to allow us to manually adjust and tweak things if we need to, which helps alleviate that concern.

From Docs to Engineering and Back Again – Susan Salituro

Currently a software/infrastructure engineer at Pixar, but has a long background with documentation.

“A career path is rarely a path at all. A more interesting life is usally a more crooked, winding path of missteps, luck, and vigorous work.” — Tom Preston

Choosing a Path

Back in college, wasn’t sure what I wanted to do in college. Went for physics with a focus on astrophysics, then moved on to math and english as a double major. No idea what to do with that for a career, so took a technical writing course. It was the only one the college offered, and was geared towards grad students focusing on their thesis, covered a lot of the basics (“don’t use passive voice” et cetera). Made her realize that there was actually a job out there for something that matched her interests: Technical Writing!

The Straight Road Ahead

There was a community! Conferences, organizations, mailing lists. Even within companies, there were usually at least some people who were invested in the topic.

I was passionate about it! Started documenting business practices, and even that was fun: it was about the user, making their lives easier.

Always something new to learn! Every project gives you something new to learn and figure out.

It was flexible! It’s often something you can do remotely, or on a flexible schedule. It’s a portable skill.

But…

Wanted to get deeper. Wandered into the woods. Started learning about information architecture, programming, ui design, classes.

IA: people who determined the infrastructure for technical writing at the company. This was fascinating. They were selecting and also implementing the tools the rest of us used.

UI: It was revelatory to go along with the UI team and see how people ended up using our documentation. It created a goal of trying to make my documentation obsolete.

Programming: Realized it would be useful to learn how to program so I could actually dive into the code and understand what was really happening.

Crossing the Plains

Started getting into API Tech Writing. Was offered the opportunity, had to make a choice between staying broad-scoped, or getting focused.

Ended up at Pixar over time, started learning DITA/XML support. Started learning how to dive into XSLT, and Python, and Make. Suddenly, wasn’t just writing code samples for others, but was actually creating work to solve their own problems.

Reaching the Plateau

You can get to the point of writing documentation build scripts without attracting some attention. Ended up getting approached to become a Software Release Engineer.

It was a new and exciting challenge, so much new information. Had the support of a manager willing to take a chance on learning on the job.

Community was still there, small team, but incredibly supportive. Able to provide the mentorship needed. Got the sense that there wasn’t a large release engineer community outside the org, though.

Flexibility also went down: we needed to be available whenever there were issues. It got tiring.

The Icy North

Needed to move to Canada for family reasons, meaning leaving Pixar. Went back to documentation roots. Took a job doing information architecture. Mixture of programming (setting up Sphinx, other tools), and also writing. Nice hybrid.

It had no community, I was alone. This provided it’s own set of challenges, but a great opportunity to learn.

The Return Home

Company went bankrupt, so moved back to California and Pixar. Now as a Software Infrastructure Engineer as part of the documentation team.

• Goal reached, right?
• Mandate: find solutions for doc problems.
• Addressing tools and process issues
• Focus not just documentation but the software life cycle

Key takeaway: take a risk, don’t be afraid to take a chance. If you’re passionate about something, it’s worth trying, even if it may fail. If you want a hybrid role, chances are, it can actually happen.

Don’t Write Documentation – James Pearson

Works for iFixIt: the goal is to teach everyone how to repair everything. This means there’s a lot of guides. It’s a highly structured wiki based system. About half the guides are user-contributed. We also provide Dozuki, a documentation SaaS platform.

Don’t Write Documentation

May sound controversial, which was kind of the intent. Often, I give the opposite talk, but this doesn’t seem like the crowd that needs that talk. Good documentation’s worst enemy is bad documentation. How often do you hear something like “Oh, I don’t read the documentation because I assume it’s going to be wrong.”

We don’t treat documentation like we treat software

A few bad examples make us assume the rest of the documentation is also bad.

We’re Numb to Documentation

We get user manuals with various devices that we never even open, because we assume it’ll be useful.

Broken Window Syndrome

A study back in the 80s. If you’re in a neighborhood with low/no crime, if you then break a window, you end up with more broken windows, graffiti, crime, etc. There’s some debate whether the study is valid, but it’s totally true in documentation.

Aside: Outdated Docs

“The docs are always outdated, so I just look at the code.” This is easy to fix: require updating docs as part of code. A commit is code + docs + tests + metrics + alerts.

Auto Generated Docs

Hate them.

Three Great Virtues of a Programmer

• Laziness
• Impatience
• Hubris

javadoc: a good tool gone bad. Programmers assume that because a tool can pull out and parse bits of their information, that’s all you need to do to document your code.

Computers suck at writing docs for humans to read. We should know this, but we keep trying.

Overly Verbose Instructions

Omit needless words. Too many steps actually adds confusion. That said, know your audience: if you’re a newbie, you may need more handholding than if you’re experienced. Experienced people feel frustrated having to wade through all the extra cruft.

Great examples of large and small project docs: Django, and Python’s Requests library.

It would be great to find ways to tune the level of verbosity. It’s hard, though.

Poka-yoke

“Mistake-proofing”

Humans will always make mistakes. Mistakes don’t have to become defects. pokayoke.wikispaces.com, mistakeproofing.com

Examples, identifying whether a merge is a feature merge or a hotfix merge. We used to have people note what it was in the commit notes, which was documented. That’s dumb. Fix the software! Specify in the code, with a spot check.

Fix product failures instead of documenting around them whenever possible.

Make Music, Not Noise – Christopher Kelleher

First doc job was to clarify the mission of an institution. Threw himself into it, wrote this huge document. Boss looked at it, and said “making sound is not the same as making music.”

Information is not the same as communication

The standards of music can guide us. This is a metaphor, not some magic 12 step process or anything. Still, it’s been useful to me.

Noise: whatever I don’t like listening to. Or more formally: sound without structure.

Sound + Satisfying Structure = Music

The search for satisfying structure is innate. Even infants naturally respond to pitch, tempo, changes, dissonance. There’s naturally some variance from person to person, but on a broad level, is universal among humans.

An example: when a song is not a song. If four people grab instruments and do their own thing without paying attention to the others, what you end up with is noise, not a song.

Yet, we do that all the time with documentation: we write our specific doc, but don’t think about other docs. Just dumping information on a page isn’t a good document: it’s noise. Ask: does it communicate?

Deliberate Noise

Q: What is the biggest lie on the internet?
A: I have read and agreed to the terms.

The iTunes Terms are 29 pages. At 90 seconds a page (which is fast), that’s a LOT of time. Why? The goal is produce acquiessence. The noise makes our eyes glaze over, so we just hit “I accept”. Which is exactly what the company wants out of that document.

We do this at work: by creating bad, noisy docs, you create job security, since people will come to you to clarify rather than trust the docs.

A musical document succeeds by satisfying the brain’s innate needs.

Through neglect, we end up with an expectation that documentation is supposed to hurt.

We can do better.

Q&A: You mention that the brain has trouble making music out of noisy docs, what tools do you suggest for fixing this?

Think about the harmony. We usually just ask “does it have all the info we need?”, but we should also ask “what is the pace? Is it too long? Is it satisfying?”

Q&A: Do you have any good examples of musical documentation?

There are totally good docs out there, but it’s hard to narrow it down, as there are a huge variety of types of documentation, I’m having trouble picking one.

Instrumentation as Living Documentation: Teaching Humans About Complex Systems – Brian Troutwine

This talk has mostly been given to software engineers, apologies if it doesn’t quite mesh.

I do things to/with computers. Software engineer, but not user-facing. I build real-time systems, distributed systems, critical systems. Works for a company called AdRoll. May seem odd to do systems work for an ad agency, but it starts to make sense: it’s less about big accounts, it’s about engineering ways to provide advertising to many small groups.

Real-time bidding:
– <100ms per transaction.
– Firm real-time system
– Highly concurrent
– Global (24/7) operation

Builds complex systems:
– Non-linear feedback
– Tightly coupled to external systems
– Difficult to model, understand
– Usually a solution to some “wicked problem”

“Social problems which are ill formulated, where the information is confusing, where there are many clients and decisionmakers…”

Bad things happen when Complex Systems fail.

The Key Problem with Complex Systems is Understanding it
– We write documentation.

Problem: Complex systems are fiendishly difficult to communicate about. Miscommunications are accidents in the making.

Documentation reduces accidents. It’s not perfect, but it helps a lot.

“If you don’t know how the system SHOULD behave, you can’t say how it shouldn’t or isn’t.”

Trouble is, documentation goes out of date. Complex Systems evolve and written words “rot” as the system moves on. Sometimes this is because Engineers fail to update documentation as the system changes. Also, Engineers can be unaware of how the system is actually used.

Accidents Happen. When designing a system, how you handle accidents is your choice.

Documentation doesn’t necessarily reflect the reality of the system: What can we do to resolve this?

Instrumentation

Instrumentation reflects the reality of the system as it actually exists. Instrumentation allows users and engineers to explore the system as it exists. Exploration, done honestly, guides us to a new, better understanding of the system. Instrumentation democratizes the organization around a complex system. (You don’t have to go through cultural choke points.)

Case Study: Exchange Throttling

We’re good at sensing patterns, but not rational patterns. When you’re working with a complex system, if you see a failure point, you need to confirm that the problem is actually what you think it is.

• All other metrics (run-queue, CPU, network IO) were fine.

What happened? We hit an implicit exchange limit. Turns out there was a bug in a tightly coupled system.

Case study: Timeout Jumps

Timeouts jump occurred only in US East, US West was fine.
All other metrics were fine
System deployment strongly correlated
Rolled back to previous release, reduced the problem.

What happened? Who knows! That’s the problem with being tightly coupled with external systems: we’re not privy to their inner workings.

Lessons Learned

It is possible to have too little information
It is possible to collect too much information, or present it badly.
Instrumentation is not a panacea — it’s not perfect.
Instrumentation may be misleading.
You need to know mathematics to make it useful.
Too much information hampers interpretation.
Instrumentation may be inaccurate.
Instruments can end up getting ignored.
Instrumentation may be used for undesirable purposes.

What can we do?

Write more documentation! Write documentation with instrumentation in mind! Provide context. Procedure manuals and visualizations reduce the need for additional expertise.

The more contextual layers you add, The more you reduce “boards of blinking lights”

“Instrumentation is like a suit. It needs to fit your own mind.”

Cross-checks and documented error margins mitigate instrument inaccuracy.

“If you don’t trust a computer because sometimes it doesn’t tell you the truth, telling it to tell you to trust it is asking it to lie to you sometimes.”

Checklists with references to instrumentation at decision points.

Collaborative workplaces, cooperatives, unions, laws, et cetera to help push back on evil use.

” I propose that men and women be returned to work as controllers of machines. And that the control of people by machines by curtailed…” — Kurt Vonnegut

Instrumentation addresses the problems of documentation, and documentation the problems of instrumentation.

Complex systems need BOTH instrumentation AND documentation.

How do I get started?

Exometer, Dropwizard’s Metrics, Scales, DataDog, NewRelic, Librato.

Q&A: What advice would you give to people writing documentation for Google Self-Driving Cars?

Consider what happens when a semi-truck collides with the car. Everything has a failure state.

@bitroutwine

We Strongly Recommend You Write Best Practices – Lauren Rother

Lauren works at Puppet Labs as a Tech Writer. Writes for the Puppet Forge, which provides ways for users to contribute modules and interesting snippets. As it’s grown, they’ve started asking for a best practices guide.

What do you mean “best practices”?

The challenge: Users have different needs, different environments, different workflows, and most importantly, different levels of experience.

The Experiment: Beginner’s Guide to Modules.

First Iteration: All the Things!

In the first version of the guide, we took inspiration from textbooks. Was sort of a huge braindump of material, organized into four sections. Wanted to presented heaps of information that anyone who wants foundational knowledge in modules may want to know.

Problem: hard to approach, first section is disproportionately huge. You know it’s a problem when you get lost in the writing when you’re editing your own work.

Lesson: Orientation: Lay out what you’re going to lay out in the section. “Today, we will be learning about science!” We’d originally excluded this intentionally as extra noise, but it turns out they serve a really important function.

Second Iteration: Introductions

Our second time around, we added headings and short introductory paragraphs. Also gave an opportunity to clean up the writing in general.

Problem: It’s hard to locate distinct items. You can’t really come back to the document. Given that this is meant to walk someone through a process, that’s not useful. In short: the doc was now readable, but not usable.

The Lesson: Guide, don’t impart. “You Kant give a Groundwork, you must give a guidebook.” These need to be documents that people can use, can reference and come back to.

The Lesson: Step-by-step: “I should’ve listened to New Kids on the Block. It’s all about the steps.” May seem obvious in hindsight, but steps make it easy to track your progress, and skip forward if you already know the earlier steps.

Final Iteration: Intros and Steps

The final version has a table of contents, headings, steps, introductory sentences, and examples! Adding the table of contents was actually useful for noticing where more examples might be needed. Giving examples should not be underestimated.

Nothing is perfect. Already taken away from it: we don’t have enough “get-your-hands-dirty” details. It’s too high level. This is something we’re hoping to address in the advanced guide.

Lesson: Logic. Understanding the “why” needs to be accessible.

Next steps

• Working on the advanced guide to modules:
  • Moar logic, moar pages
  • building a module in the doc, linked to GitHub with branches for each section

Recommend checking out the RFC Language Guide for recommendations on language for best practices guide.

Q&A: Did you get feedback during this? When did it become user facing?

Started by releasing to the Forge team, then to the rest of the engineers at Puppet, then released to top contributors, then released to attendees at PuppetConf, then finally published it. This worked really well to get structured feedback in stages so it wasn’t overwhelming.

@GrandmaHenri

Wabi-Sabi Writing – Scot Marvin

What I’ll blather about

• Wabi-sabi defined
• Agile somewhat defined
• Writing principles I’ve found useful.

A visit to the garden

• When stressed out, it can be useful to visit the japanese gardens.
• While there, picked up a book on wabi-sabi. Discovered it was super relevant.

Wabi Sabi defined

• Ironically, it’s mostly westerners talking about it.
• Grew out of Zen Buddhism
• Tenets
  • Beauty is in the impermanent
  • Beauty is in the imperfect
  • Beauty is in the incomplete
• Aesthetics
  • Rustic
  • Tranquil
  • Simple
  • Clear
  • Asymmetrical

What it isn’t:

• wabi-sabi != Luddism

(Aside: Schematron is pretty rad. Also, QA plugin for DITA)

• wabi-sabi != complacency
  • Let go of perfection, strive for excellence.

Agile Defined (Sort of)

• Salad Bar Agile: everyone picks and chooses the parts that they like. That said:
• Find out where you are
• Take a small step towards your goal.
• Adjust your understanding based on what you learned
• Repeat.

Four Suggestions

• Less Faulkner, More Hemingway: Clear Writing.
  • Faulkner, great, lush, long writing. Lovely to read, but bad documentation.
  • Hemingway: short, direct sentences. (Check out Hemingway App: grades you on writing clarity.)
• Less Coltrane, More Davis: Tranquil writing.
  • Coltrane known for controlled chaos. Sheets of sound. He’s taking you for a ride, hope you don’t fall off.
  • Davis, king of cool, calmness. Economical restraint in what he does.
  • When users come to your documentation, it’s often a last resort. They’re stressed out, tired, under constraints. A good goal is to try and put support out of business (never gonna happen, but it’s a goal). They should feel like you just said “It’s okay, I’m going to help you get through this.”
• Less Versailles, more Ryuan-ji: Simple Writing
  • Gardens of Versailles are elaborate, magnificent, complex.
  • Gardens of Ryuan-ji: simple, zen-like.
• Done is beautiful. It’s hard to complete something, but you can get something done.
  • Think about “Sweet Genius” show: cooking show with limited ingredients, but halfway through, they bring out a new ingredient. You have to roll with it.
  • Embrace the cracks and crevices of your work.

@scotmarvin

Q&A: Could you mention more about the QA Plugin?

It’s a free DITA plugin, It basically creates XSL rules you can verify against.

Q&A: When working in agile, are you sprinting alongside the devs, or a separate sprint?

Hopeful ideal is one sprint behind: feature gets done, we spend the following sprint documenting it. Reality tends to be a few sprints behind, simply because things come up and done is rarely done.

Strategies to Fight Documentation Inertia – Britta Gustafson

@brittagus

Discussing how we revived our community documentation and wiki. Pretty much every documentation project could use more enthusiasm. Works for Cydia.

We started out as a fairly generic mediawiki install. Text talked about how challenging it was to start.

Now: covers lively, topical stuff, there’s inside jokes, but it also generally more approachable.

We need to document what we’ve figured out about private APIs, and leverage things Apple doesn’t normally allow. A lot of this documentation comes from volunteers.

For a long time, we didn’t have a lot of documentation. You just had to figure it out on your own, and asking questions on IRC.

Started out as a community manager, mostly focused on customer support. Didn’t do docs.

Got involved in OpenHatch, learned more about contributing to open source projects, new perspectives. This made her realize that she actually has a lot to offer the wiki. Started working to edit the wiki and improve it.

Joining open source projects is actually a great way to find out how to help in your work.

Strategy #0

Have somebody who cares hang out where the developers are.

STrategy #1

Talk to newcomers and beginners. Established people don’t see the point, they already know it. Newbies ask questions, are enthusiastic, will read it all, and ask redundant questions which lets you know when existing answers are too hard to find.

Strategy #1A

Help identify what is useful info to write down. Asking “Would this be useful to put on the wiki?” It doesn’t occur to people that they can contribute easily.

Strategy #1B

Ask encouraging questions to counter anti-documentation concerns. If they’re resistent to “documenting”, sometimes they’re less reluctant to write up “pre-requisites”.

STrategy #2

This is a marketing problem: people are intimidated by documentation and complex sites. Make the homepage enticing to click!

Strategy #2A

More marketing: Build new articles that attract more visitors. For example, making a list of open source projects people could check as examples. This made the devs feel good, and it got shared a lot, and people signed up for the wiki so they could add their own.

Strategy #3

Make writing more fun: show that people read it. Create a good feedback loop.

Strategy #3A

Make it more fun by copyediting new stuff. (Improves readability, but also proves somebody read it!) Also, people who aren’t super proficient writers often appreciate the edits.

Strategy #3B

Make the wiki fun by making it look active. No one likes to hang out in a ghost town. Make sure the recent changes page always has new things. List new articles on the home page, so it feels fresh and active. It needs to not feel static.

Strategy #3C

Make it more fun by thanking people. Not getting thanks is the definition of a “thankless task” — spending the 30 seconds to thank someone on the talk page, or twitter, or IRC, makes a huge difference. Be specific, and be timely, and be public about it.

STrategy #4

Be there to give people permission. People need to know it’s okay to edit/write, it’s not enough for some.

Strategy #5

The docs system needs docs. Even if you think it’s easy, it isn’t for everyone, and a reference/cheatsheet is nice.

Strategy #6

Leave rough edges for others to smooth out. It gives people a way to immediately contribute. Kind of social engineer-y, but it works.

STrategy #6A

Write bad first drafts as motivation. If you get it out there, and show it to someone who knows, they’re going to want to go fix it. Few people like starting with a blank page.

Strategy #???

Maybe I’ll end up learning development to help myself write better dev documentation. We’ll see!

[Note: There’s a Write the Docs meetup in SF, go look it up!]

Lightning Talks

Kelly: There’s been a lot of talk about getting engineers involved in documentation. We’ve started doing engineering pre-docs. Goal was to streamline the workflow, and figure out the things the support team needs. We came up with 8 questions that we ask engineers when doing development. Philosophy of “Dev isn’t done until doc is complete.” Engineer were actually really happy to have something they could fill in. The questions aren’t important, but.

1. In your own words, what changed?
2. Did the market change?
3. Was a configuration added? What?
4. Were there any schema changes?
5. Were there any data migration steps?
6. Was there any data logging added or changed?

Ed Borasky: Reproducible Journalism for Mobile: The problem: an impedance mismatch. Thinking about science journalism in particular: we expect you to be able to show your work, but there’s a limited screen space, and a distracted reader. Creating a project called RepJournMobi, which is a collection of useful components for handling scientific behavior. Have applied with Knight Foundation for a grant to pursue this, looking for additional sponsors/support. Building a prototype.

Corey Gantz, MindTouch: How to play Risk and create documentation at the same time. Teams of 2, pick an article from a list, basic guidelines for what an article needed to be accepted. If you submit an accepted article, you get a card. You can use card to steal teammates, goal is to have the largest team and most docuentation. Spelling errors you have to do a pushup, and if you’re missing article requirements, you have to sing a karaoke song. Worked really well, everyone had fun, and wrote a lot of docs in a short time.

Bob, from Conway: Peer Instructional Designer, does more peer training than technical documentation. In split between documentation and presentation, what about training? Kind of its own thing as well. Three assumptions: information isn’t knowledge; knowledge isn’t performance; training isn’t telling. Training results in a behavior change, otherwise it’s not training. Behavior change comes from practice. Looking into Action Mapping. Example: Identify a business goal that is concrete, measurable. Identify the actual goal and performances necessary to achieve that. Design activities where people get to perform the actions needed to get batter at it. Establish what the minimum is necessary to achieve success. Training becomes activity based instead of topic based.

Let’s talk about typesetting and its relation to documentation. Printing is great, but a lot of hard work. Also, because typesetting fell out of use quickly, no one kept the documentation. Discovering who to talk to about it even is hard. It’s a lot of chasing down more and more information, finding the right people to talk to. End result: a company reviving the nearly lost art: metaltype.org

The value of sharing and documenting ideas. Has been a music teacher for a while, and was frustrated by the state of training materials, so started cataloging what was good and why. Realized, this is useful, and should probably share it. Got to thinking about the difference between encouraging a participatory culture vs presentational culture. The idea of actively inviting others to join and being inclusive. Have created snowdrift.coop to help create this sort of inclusive culture.

Chuck: Reading Green Eggs & Ham. Yes, seriously.

Scaling for Support without Losing Personality – Leona Cook

Support, In-product design, documentation & tutorials — they’re all connected.

Different people process information differently. Some learn visually, audibly, kinesthetically, etc. We need to think about how we can avoid shutting out people who learn differently. As writers, we can help them by remembering that not everyone is like us.

One hat is not better than another. Engineers “make buttons” and everything involves personality. It’s all about how you choose to view.

Support, design, docs, these are where personality for the brand is shown. It’s important to recognize this early, and plan for it while you scale.

In-product Design

• Things to think about
  • Devices (mobile, desktop, etc)
  • Visual Order
  • Large -> Small
  • Bold -> normally
  • In & out” what comes next in the flow, and where does it belong (page, screen, section, etc). How did they land on this page? Where do they go next?
  • Whitespace: makes docs less overwhelming.
• Principles of good design can apply to other areas as well.

Support

Support are the unsung heroes of any company.

• The only hat that deserves the title of “ninja” — Strongest link to triage.
  • Engineering improvements
  • Design improvements
• Any 1:1 interaction with a user/customer is an opportunity for learning
• The best ones naturally become scarce.

Documentation & Tutorials

“Microsoft’s original plan was to make money selling programming languages, of all things.”

• Tutorial is a word that used enough in the world of docs — we should change that!
• Docs are good, but tutorials are better.

Getting Stopped Experience: Improving Your Content’s First Impression – Jared Bhatti

@jaredbhatti

Jared works at Google. Starting a new project at google, TW for Google Cloud (developers.google.com/cloud)

Compute, Storage, App Services, lots of components in each. Each has their own getting started process, and yet they also all interact with each other.

Presentation Goals

• Start a conversation
• Define the journey for “getting started”
• Share metrics.

Hands On: Getting Stopped! (2 minutes)

Think of a product or service that you work on:

What are some of your challenges for getting users started on your project?

For instance, getting people onboarded as quickly as possible that shows them the options but also gets them active quickly.

Hands on: Sharing is caring

1. Introduce yourself to another person
2. Give them a handshake or high 5
3. Tell them one of your getting started challenges.

Common problems

• Findability (how do people find the docs?)
• Complexity and density (too focused on the complex problem we’re solving, instead of covering the simplicity of the solution).
• Poor connections with user communities
  … and many more!

Break it into three steps

1. Find helpful solution
2. Get something working
3. Get your thing working

Find Helpful Solution

Improve discoverability. Make sure it’s easy to get to the actual relevant information.

Fixing Findability

• Dogfood finding your content
• Understand how your users get in
• Find complementary content
• Look at your competitors.

Get Something Working

“Hello World” Was getting too complex (24 steps to do hello world in app engine!)

User Research: started collecting data and watched developers.

Key Questions:
1. How are we doing?
2. What tools and resources are most utilized and useful?
3. What are the pain points?

Chart out the frustration levels in the learning process, find the line where things finally start to even out, figure out what cliffs and spikes come before that.

User First Principles
1. The user is always in control
2. Give the user what they want quickly.
3. Reduce friction everywhere
4. Show, don’t tell.

It is critical to reduce the point of perceived pain or frustration.

Got Hello World down from 24 steps to 4 based on these principles. Time to Hello World went from ~4 hours to ~15 minutes. From there, made a sandbox (Cloud Playground) that gets TTHW to 30 seconds.

Measure Success

• Dogfood your product
• Friction logging
• “Time to Hello World” (identify an appropriate metric)

Keep the conversation going

• Community Outreach
• Happiness Surveys
• External partners

Go to your users: GitHub, StackOverflow, etc.

How would you improve your users getting started?

1. How are users getting to your docs?
2. How long does it take to get to “Hello World”?
3. What metrics are you collecting?
4. How are you interacting with your larger community?

Q&A: What percentage of feedback do you get? We seem to get very little.

We get way more responses on the consumer feedback, but what we get from the feedback form tends to be really topical and good.

Q&A: Do you ever have an entry level point that is too low and don’t want to try and support?

Arguably. Ideally, we try to make it more about combining points rather than ignoring them — like, it’d be great to try and merge marking and educational material together more.

More Than a Reference: Better APIs Through Empathy – Zack Corleissen

Senior Technical Writer at Moz, in charge of API documentation. We have 1.5 public APIs.

Loves API technical writing: the challenge of taking something technical and explaining it well.

Together, We’ll Cover:

• Q&A
• Defining Empathy
• Writing Empathetically
• components
• Examples
• Follow up

What are You hoping to get out of this talk?

Empathy is the ability to mutually experience the thoughts, emotions, and direct experience of others.

To write empathetic API docs, you need to share the user’s needs.

• Use your own API.
• Use other APIs and read their docs.

Writing Empathetically
– Know Your Readers. Who is using your API? Get good metrics, it may not be who you expect.
– Write For Your Readers. May seem obvious, but it’s not obvious in practice. It’s easy to fall into the trap of writing for ourselves.
– Tell True Stories. Chances are, if they’re in your docs, they’re already sold on the product, but they need to trust that what you’re writing is true. So be honest.
– “Why does this API matter?” — it doesn’t have to be long, but you need to tell the truth and address it. What is it solving? What does it accomplish?
– Provide a friendly UI: Not easy, but if you can encourage this, do this.
– Single-page docs. End the click insanity!
– Better typography! It matters!
– Engage the empathy of allies.
– Practice empathy for just your readers, but for others too. Talk to the support team, test, other stakeholders. Find out what surfaces through them.

Empathetic docs require more than reference completeness. That doesn’t mean things like pydoc and javadoc don’t have value. It’s important information, totally. It is not enough.

• Explain how to get started.
  • For things like REST APIs, explain how to form calls.
• Give the most attention to your API’s most common endpoints and methods — weight your time and organization appropriately.
• Lavishly document failure states and edge cases: what to do when things go wrong.
• Provide meaningful error messages.
  • For Rest APIs, provide meaningful HTTP response codes.

Examples

Good example: Twilio Rest API. Descriptive, includes brief text explaining the point.

Rails API docs. Used to be AWFUL, but has improved recently. Good example of weighting their doc organization.

MozScape API Wiki: Introductions, References, Samples. It’s so-so, he’s not happy with the UI, and sees areas for improvement (he wrote it).

Google AdWords API: Some good things about, some things bad. Hard to find help or support, tasks.

Apache Lucene API: Actively hostile to readers.

Twitter API: Great in a lot of ways, but you still end up with random holes in documentation, details that aren’t provided (like when something will randomly switch from returning an int to returning a string).

Empathetic API docs challenge you to deepen your technical skills and care for the needs of others… but empathetic API docs delight your readers exceptionally.

Your users time, and YOUR time matter. Life is too short to not write empathetically.

Ditch Your CMS: Git + Markdown + Static Sites Generators – Patrick Arlt

Who am I?

• Experience Developer
• Esri PDX R&D Center — previously known as Geoloqi
• I love building products for developers
• Started working on ArcGIS for developers

ArcGIS for Developers: do something great for your developer community.

Started small, launched one page, took several months, got up to 6-7 pages over the next several weeks. Started adding functionality… realized, we had no documentation. /documentation just forwarded to other sites.

Turns out What we had:
– Thousands of pages of doc, buried in an old CMS.
– Dozens of products
– No one liked using it, even ended up running other wikis and then just copy-pasting into the CMS.

What we wanted: A clean way to make it easy to create and share good documentation. Came down to realizing we wanted to tear it all down and start thinking about BUILDING documentation, not just writing it.

Decided on a solution that built on top of existing infrastructure that people like to use, like git. Using static site generators, like Jekyll. Treat docs as source code.

Nice benefit: static sites take all the hard parts of building a website and lets writers focus on writing.

Selected Markdown because it’s super simple, extensible, and was already in use because we use GitHub, and they use MD for docs.

We rely a lot on Git (and GitHub).

Used by a lot of developers to manage source code.
– Versioning and rollback
– Development workflow
– Release management
– Collaboration

GitHub additionally adds some extra tools, like issue tracking, wikis, and pull requests.

Aside: you know placekitten? Let’s make placesloth!

Provides:
– Control
– Flexibility
– Extensibility
– These tools are designed to be extensible to fix use cases.
– Ownership
– Teams have been eager to learn these tools because it lets teams own their content more.
– Collaboration
– Allows anyone on any team to look at and edit documentation

This wasn’t an easy sell: “But do all my writers/proofers/editors have to learn all this?” Well… yes. But is that actually any more complex than the bar on a complex CMS system?

“But what about all the stuff in our CMS?” That’s okay. You can serve static files along side a dynamic system, generally looks for the static file before dynamic files, so it’s an easy migration.

“But everyone has to preview the site locally?” Also true, but you can automate a lot of that way.

Where are we going?

• More automation
• More custom tools
• More training

In the end

• Bring developers and documentarians closer together
• Documentarians start thinking like developers
• Encourages collaboration and communication

@patrickarlt

Q&A: For sophisticated documentation, developmental changes, do you have a workflow that helps with this?

We haven’t really encountered an occasion where we’ve been blocked by limitations of Git yet. We do also leverage templating tools that are built into the static site generators.

Documentation as a Product – Mark Tattersall

A product is the result of an action or a process, so documentation IS a product. So why don’t we talk about it as such? It’s overlooked as something in support of a product, and is often the last thing people think about.

Docs Thinking => Tactical Thinking
– Audience
– Tone
– Content Management
– Format

Holistic:

Product Thinking
– Problem solving
– Vision and Alignent
– Personas
– Success factors

Objective of this talk:
– Go write some killer docs!
– Provide a heuristic for execution
– Audience
– Reference
– Mobile
– Testing
– Community

Product Manager @ Braintree

The API is a effectively our product, so documenting it well is incredibly important. When he came in, the docs were sorely lacking, missing a lot of useful information. First product he shipped was the docs, and has become sort of the “docs guy” there.

Docs at Braintree is complex: a lot of platforms, languages, writing something just once doesn’t really happen.

We’re in the process of coming out with a v.2 of our documentation to better serve developer’s needs.

What problems are the docs solving?

If you can’t understand what your docs are trying to solve, why are you writing them?

Docs are for existing & potential users. This is a bit of a shift, but a real one: docs can play a large role in the sales/marketing process, in particular if you’re selling an API or a service.

“Marketing is for Christmas. Docs are for life.” This refers to the fact that people switch off when they feel they’re being actively marketed to. It’s entirely possible that the docs will be the first meaningful interaction you have with a potential user.

Who will be using your documentation?

• Create personas of your users.
• Get out and TALK to your users.
  • If not you, reach out to those who do — sales, support, etc.
• It’s not a linear relationship, people will drop in and out of your docs.

How should your documentation communicate with your users?

• What is the voice & persona of your product or company?
  • Chatty? Formal? Humorous? You need to walk a fine line, but it’s important to get right.
• Documentation can be enduring connections to users.

Where do your documents sit in the company?

• Understand where the product & company are going.
• If a big change is coming, it’s good to know about it so you can prepare for it.
• What should be fundamentally apparent about the product when landing on the docs?

What does success look like?

• Are your users achieving their goals when using your docs?
• Are your docs furthering the company and product goals?
  • Think about your metrics. Funnels, analytics, calls to action, engagement.

What do your competitors’ docs look like?

• Learn from your competitors & and from different fields. Competitive analysis can really help solidify what’s needed.
• Do different & Be Better!

Execution

Fundamentals

Information Architecture: Map out your content, what is the context, who are your users?

Make sure the UI is responsive, can still be worthwhile on other devices/screens.

Formats

Quick Starts & Tutorials

Interactive Sessions: Letting users actually interact with your material creates raised engagement and immediate feedback.

Example Applications & Test Environments: Different people want different things — some want applications they can dive into, break, and then reverse engineer out of to learn how to do it.

Code, comments, and readme’s

Reference: make sure users can both search AND browse, both are important.

Community

Encourage your docs to have a life outside of your environment — urls should be readable and semantically relevant so that links from other sites are clear about where they’re going and why it might be valuable to a user.

Support Documentation: There’s often relevant information, and related articles should be linked.

Content Management: Do the preliminary thinking first before deciding on your CMS. Think about the formats you want to cover, who will be writing, what technical proficiency will they have, how hard is it to maintain?

Analytics

You want to know who is coming to your docs, what is most viewed, where people are bouncing out.

Iterate!

Move quickly, keep improving! Because building a product is hard and you won’t get it right first time around.

@foxes96

Q&A: Can you elaborate on the interactive sessions?

Inline, in the docs/website, provides a lightweight environment for getting to “Hello World” quickly, without having to create a local environment.

Closing Thoughts

Videos are already going up, should be all up as soon as we can.

If you made notes (Andrew Spittle), thank you, please share them.

Email will go out later with links, useful followup, and probably a small survey — please fill it out so we can keep improving.