Write the Docs 2014 (Day 1)

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

Introduction – Eric Holscher

Welcome to Write the Docs! This is a community conference – no profit, inexpensive, more about building community and learning things. This is version 1.0 (last year was version 0).

EU was in Budapest, about 100 people.

We still have no idea what we’re doing — bear with us, give us feedback.

Your Job:

  1. Make Friends
  2. Learn something
  3. Have fun

How We Get Along:

  • Welcoming
  • Open
  • Supportive
  • Positive

If you see a group of people you don’t know, go and join them. If you’re in a group, welcome new people.

Code of Conduct:

  • Be Excellent to One Another
  • Talk to an organizer if you have any issues.
  • (Fuller text is online.)

Agenda:

  • Wide ranging
  • Documentarian Bound

Lightning Talks:

  • Think about something you want to talk about
  • Signups are at the reg desk — talk about something you care about.
  • After lunch both days — 5 minutes or less per.

Lola’s Room

  • Hallway track!
  • Free space in the morning
  • A few selected talks after lunch
  • “Unconference” after that.

Unconference topic: career path discussion, a chance to discuss among peers what options there are and what ideas people have.

Thanks

  • Sponsors
  • Speakers
  • Volunteers & Staff
  • Attendees

Stay in touch

Story Time

Last year, we put together the conference in about 2 months, with a hard deadline because one of the organizers was going to run away and hike the Pacific crest Trail. Big takeaway: the people on the trail are amazing, and a real community. The goal of the conference is to build that sort of community among documentarians.

Flow: A Permaculture Approach to Documentation Projects – R.N. Homer Christensen

Topic is using permaculture principles on documentation products.

Homer Christensen:

  • Technical Writer
  • Practicing Permie
  • Over the past three years:
    • Replaced lawn with food forest
    • Replaced documentation with single source solution

What I’ll cover

  • Introduce permaculture as a design science
  • Describe foundational principles
  • Relate those to Documentation

Permaculture == Permanent Agriculture. Grew out of Australia in the 80s.

“The philosophy behind permaculture is one of working with, rather than against, nature, or protracted and thoughtful observation rather than protracted…”

Also worth looking up: City Repair, a PDX based group reclaiming urban spaces for growth and community.

Mollisonisms

  • Work with the elements
  • Diversity gives stability
  • The problem is the solution
  • Make the least change for the greatest effect
  • There is no limit to the richness of design

Holmgren’s Model:

  • Ethics Hub (look it up: Permaculture Principles website)

It’s about building a resilient system: easy to maintain, getting most results from least input.

Principles in Documentation Projects

  • Observe
  • Design
  • Evolve

Observe

  • Without preconditioned ideas
  • With an open mind
  • Note whatever draws your attention (You’re receiving information about the entire system & patterns — intuition will kick in.)
  • If you feel like something is important, note it down.
  • What are the patterns and flows of energies?
    • Are there distinct phases?
    • What is the corporate culture?
  • What resources do you need to complete this project?
  • What is the duration of the project?
  • What is the goal?
  • What is available?
  • What are their skills, abilities, and natural inclinations?
  • How can we combine team members to collaborate and cooperate to be beneficial at complete project tasks?
  • Living systems have natural proclivities and team dynamics are living systems
  • Be aware of project scope, timeline, culture, etc.
  • Discover the patterns of the org, team, and readers
  • Look into ways you can innovate, improve, or provide additional benefit

Design

  • Consider zones of access — “right out the front door” vs “out in the back pasture”, how often is it visited?
  • Work with the energies — go with the flow
  • Make a small change early to create the largest effect
  • Value diversity
  • The edge is where the action is (more open channels, fewer bottlenecks)
  • Encourage collaboration and cooperation
  • Design for multiple yields
  • Stack functions

Zones of Access:

  • Where can you gain access to info
  • What does your reader need to know
  • …

Cooperation != Competition

  • Cooperation is the basis of life systems
  • Collaboration within and among teams
    • Increases communication
    • Allows chunking of work
    • Increases stability

“The importance of collaborative processes if often ignored because of the urgency of direct action. Groups can work more successfully together when participants are engaged and feel connected, bringing better outcomes in the long term.” — Tefford

Design: Documentation

  • Determine what information your reader needs most frequently and urgently — and make it easy to find
  • Increase the edge
  • Distribute and chunk work to reduce risk
  • Assign work based on abilities rather than titles
  • Look for ways to make efficiencies early
  • Single source & reuse content not only among documents but also among teams.

Evolve

  • Know that your system will evolve — let it!
  • Continue to observe
  • Grow your soil
  • Refine your system
  • Keep a feedback loop

“Grow Your Soil” — permaculture adage

  • Soil is the most valuable asset in agriculture
  • Soil == People
  • Help your team:
    • Evolve
    • Learn new skills
    • Take on tasks that help them Grow
  • Lessons learned sessions
  • Measure & evaluate
  • Be open to new ideas
  • Train team on new skills to fill needs
  • Provide free-exploration time

Q&A: Did the turnaround in the team’s happiness get affected by the change of tools (NetFlare?)

Previously had been using Word to write docs, switched to Flare. Might have had some impact, but more of it was disconnect at a managerial level, not enough communication, too many roadblocks to good communication. Two managers who didn’t talk (instructional lead, training manager). Both got fired, merged the teams, much better.

Q&A: Challenges of establishing permaculture in a large toxic environment. Can this kind of approach scale to large enterprise with many projects and teams? How can we do this as individual contributors?

Not sure. What individuals can do is try to establish your own connections, develop your own channels, and (gently) let people know what you want help with. You may be able to sell it based on costs — single-source and adjusting the team as needed saved 20-30% budget-wise.

Q&A: As a manager of a team, there’s also a need to convince people that you can get it done on time. What sort of strategies to talk up the chain to justify the time and space you need?

I avoid competition language up the chain. Not what I want to convey as a solution. I focus on the efficiencies of putting together a well thought out system, that it helps in the long term. Show the outcomes of investing the time now. Finding ways to reduce risk: if only one person knows everything and then they leave, you’re out of luck. Cross training reduces dead times, since when someone is blocked, they can go help another person.

homerchristensen.com, slide deck will be up later.

Communities are Awesome – Ali Spivak

Ali Spivak: works at Mozilla, works on MDN: Mozilla Developer Network, an open source wiki, documentation site.

Mozilla is a non-profit, mission-based company: mission is to promote an open internet. The way it works is through community.

The web is big — there’s a LOT to document. Not just Mozilla products, but also things like HTML/CSS/JavaScript/Canvas, etc. About 2 million users a month on MDN. Standards evolve a lot and don’t stay the same, so we have to stay on top of things.

5 paid writers, but a lot of what they actually do is working with the community. 2-3 paid contractors working mostly on product writing. Core volunteers is more like 200ish, active on a daily or weekly basis. 500ish “Active” (an edit a month), 1500ish occasional (1 every 3-5 months), 5000 people who’ve contributed over the life of the site.

Community: a feeling of fellowship with others, as a result of sharing common attitudes, interests, and goals.

Community handles edits, typos and corrections, translations (entirely, into 35 different languages, 15 with substantial coverage), reviews, tagging, help build the information architecture.

Organize “Doc Sprints” where we get a bunch of volunteers together and we get together for a weekend and just focus on writing. Sometimes on a subject, sometimes self-organized. This is also generally organized by volunteers.

Big benefit of volunteers/community: providing diversity of perspectives, are able to surface issues that we might not otherwise think about. For example, people in other parts of the world surfacing concerns about low bandwidth.

“A strong community benefits the individual, the community, and the greater society. People of all ages who feel a sense of belonging tend to lead happier and healthier lives, and strong communities create a more stable and supportive society.”

Foster a sense of trust with your editors. Empower people to contribute, and you will get results. Lower the barrier to join, and make it clear that it’s okay to make the edits. It’s about peer respect, that it’s collaborative and that their input is valued.

“The idea of community may simply come down to supporting and interacting positively with other individuals who share a vested interest.”

Volunteers aren’t minions: you can’t really tell them what to do, provide them tools to discover what’s needed rather than simply say “Hey, go fix this page.”

Who writes docs? Why would people spend free time writing it?

Comes down to intrinsic and extrinsic motivation. Extrinsic motivators can actually be demotivating (money, fear, reward, etc). Intrinsic motivation is things like being part of something bigger, being able to contribute expertise to something larger than they could do themselves.

Highly recommend “Drive” by Daniel Pink, discusses more about motivation.

3 Elements of Motivation

  • Autonomy: the desire to direct our own lives
  • Mastery: the urge to get better and better at something that matters
  • Purpose: the yearning to do what we do in the service of something larger than ourselves.

Think about the Ten Principles of Burning Man.

“Participation: everyone is welcome. We achieve being through doing. Everyone is invited to work. Everyone is invited to play. We make the world real through actions that open the heart.”

Transparent community-based processes promote participation, accountability, and trust.

Also look at Zappos Family Core Values.

It doesn’t really matter what your principles ARE, so much as that you actually follow them. Your principles need to inform your culture in a real way. History is littered with companies who lost connection with their users. Community is a way to keep that connection.

Consensus can feel slow, but doing the wrong thing is slower. Taking the time to get consensus ends up with a smoother and faster implementation. “Get it right at the beginning.”

What Mozilla does may not be the right way for your company, but some of the ideas can be used. Think about how you can create community within the company, and apply the principles of community to your documentation needs.

The New Sheriff In Town: Bringing Documentation Out of Chaos – Heidi Waterhouse

How to bring some order and structure to a chaotic environment. Her specialty is walking into companies who’ve never had a tech writer/documentation role before, making it work, and then riding off to her next company.

Get a Sheriff’s Star

If they believed in documentation, they’d already have someone doing it, so you need to get over the imposter syndrome and make it happen.
– You are here because you’re an expert
– You..

Set up Shop

  • Make your own seating chart/map, note names and specialities
  • Draw a map of the existing docs and how to get to them — there always is some. Random folders, wikis, etc. Make sure you have access, might mean some prodding. You need visibility everywhere.
  • Get to know the neighborhood — competitors and users.

Draw Fast

“I have a business card that says “Better and cheaper than having your developer do it.” ”

  • No time for frills
  • Deliver early, deliver often, OR talk about why you couldn’t.
  • You get precision between emergencies, but deal with the emergency first.

Save the Townspeople

  • Address biggest internal pain points. Wins friends, influences people, quiets the impostor syndrome.
  • Give them a structure to provide feedback. Use bug tracking for documentation! Existing tool, they know it, and there’s visibility into what you’re doing.
  • Not all documents are for everyone, but if you can’t visualize the end user, you’re probably just wasting time.
  • Townpeople is a broad category.

Check for scorpions

  • Hoarded documentation
  • Stuff from the last Sheriff: sometimes you aren’t the first, and the person before has left behind certain “feelings” among users. Damage control may be needed.
  • Bring in the vigilantes: deputize them, these are your advocates for documentation, ask them to proof/edit those articles they care about, so they’re involved.

Build Infrastucture

  • Build a cadence for everyday life, less reinventing the wheel.
  • “Newspaper” — show what you’re doing, show it’s not just a random cost center and that people think about docs when releasing.
  • “Telegraph” — Communicate with peers elsewhere.
  • Plat your documents, find gaps — should have: use, configure, customize, fix, reference. “Plat” refers to designating areas for different uses.
  • Plan for succession: you may win the lottery, or get laid off, or get hit by a bus: you need to have things as shareable as any other part of the code.
  • You are part of the town. Be a participant.

@wiredferret

Q&A: Green Field Documentation?

Going into an untouched area — new products, new situations.

Q&A: Dealing with legacy frustration with doc writers?

Find their pain points and solve them. Often, the frustration comes down to feeling like the prior writer didn’t listen to them. Easiest to show them.

Ignorance is Strength: Writing Documentation by Learning as you Go – Amalia Hawkins

Amalia is from MongoDB, software developer.

Ignorance can be a strength. As documentarians, we want to spread knowledge, the struggle of discovery and learning is beneficial!

Who am I? Graduated in May, Started work in August — enthusiastic!

Part of work in college was as a TA, and hiring other TAs. Often, the people who became the best TAs are the B and C students, because they had to struggle and try to discover a good mental frame for the subject.

Got to MongoDB, had to learn. Mixture of sifting through code, and reading existing documentation, and asking questions. These all fall short at some point — reviewing code won’t tell you the WHY something was implemented that way. You can’t even always ask someone at the company — maybe they left, or are busy, or don’t remember.

TL;DR: lack of internal documentation causes growing pains, makes it very difficult to scale. Often engineers aren’t really productive for a month+ after hiring because of onboarding and ramping up.

Makes it harder to communicate between teams: people who may have a vested interest but don’t have time or availability to spend two weeks figuring out a piece of code. Also, as you expand to additional locations, conversation becomes more difficult.

Example: struggling to learn a particular feature, struggled for two weeks, finally managed to pull aside the CTO who explained it in 10 minutes. That’s not scalable or useful, at all.

Easy to feel some trepidation because you aren’t the expert. Ignore that.

Lesson One:

Write Anything: wrong things are better than no things — it’s easier for people to nitpick and correct than to write it new. If you’re frustrated enough to rant about it or kills a lot of time, you should write about it.

Lesson Two:

Find your allies. Chances are really good that other people are confused too. It’s easy to have impostor syndrome, but really, chances are that lots of others are confused too and you just don’t know.

Lesson Three:

Spread out the work. Content, Format, Critique.

It’s hard to ask people to help when they’re already so busy. Don’t feel bad — it can actually help people understand something more effectively. By breaking down the parts that need to happen, so that engineers who are frustrated and learning can just get the content out there, and then someone can sort of clean it up, format it, and then someone else can critique it for correctness. Makes it feel less onerous.

Internal docs: don’t worry about whether it’s the most professional, most polished, think about effectiveness and usefulness.

What’s next? Open source <3! We’re in the process of cleaning up our internal articles to leverage them for external use as well.

Q&A: Can I read that database context rant?

I’ll see about publishing an excerpt with my slides.

Q&A: Thank you for calling out that you need to get your crappy draft out.

Q&A: What’s your process for getting internal docs ready for external use?

A lot of it comes down to cleaning up tone, making things consistent across docs. Making it a little less casual, and also culling parts that might not be relevant outside the org.

Did it in Minutes: The Art of Documenting Meeting Notes – Mo Nishiyama

@synthcat

Yes, the title of the talk is a reference to the Hall & Oates single “Did it in a minute”

What’s so special about meeting notes? They’re boring, plebian, no one likes writing them.

Some background: Got excited about sketchnotes after last year’s Write the Docs conference. Was in a toxic work environment, so mostly just doodled, but it looked like I was taking notes. Finally someone noticed that it looked like I was studiously taking notes, and asked me to take the notes every week from then on. Oops.

Realized needed to get out of the mindset of notes being regurgitation, and make it about curation.

Ask: Who is your audience? Who will be reading these? What’s important to them?

Create a shared need: What are people going to get the most out of their notes. Ignore chronology. Format to draw attention to the most important stuff.

WTF: Write the Facts. Focus on the facts, you don’t need to deal with every opinion or mention. You don’t need to write 88 lines about 44 opinions.

Engage your subject matter experts: if something came up in the meeting, verify before you send out the notes.

Make sure any action items are CLEAR: Who, What, When. Vague goals aren’t useful to anyone. Action items are actionable.

Meeting note distribution: use collaborative tools rather than just tossing into a text editor and emailing it out. Allows the notes to be updated and corrected without having to re-send out the notes.

Templates can save time, don’t need to be complex, filler text is fine.

Goal of meeting notes is to disseminate information and answer questions people may have. It frees you to work on high value work instead of catching people up.

Fix TL;DR: Add humor and add personality, easter eggs, make the notes engaging.

There are some exceptions, of course: chronology sometimes matters. Regurgitation sometimes is necessary. Sometimes style guide restrictions.

Hacking the English Language (Or, What we can steal from programmers) – Nina Vyedin

It’s easy to end up stuck at the beginning. How cool would it be to have a template that actually works, that’s already a doc?

When I say hacking, I’m talking about applying useful programming practices to our writing.

How do we avoid the empty page?

  • Templates. Don’t start with a blank page!
    • Find a format you like, and start with that.
    • Find docs you like, and turn them into templates. It’s not about the content, it’s about giving structure you like.

Are we asking the right questions?

  • Make a spec! A doc for a doc.
    • May sound overkill, but it doesn’t have to be long. The point is to define the questions you’re actually trying to answer.
    • What is the audience expecting to learn?
    • Who is the current audience?

Dealing with outlines — it’s never the outline at the end that was expected at the end.

Design Patterns:

“A design pattern systematically names, motivates, and explains a general design that address a recurring design problem to object-oriented systems. It describes the problem, the solution, when to apply the solution…”

  • Start with an architecture: what type of doc are you trying to write?
    • Telling a story, tutorials, walkthroughs
    • Painting a picture: a snapshot/image.
    • reference
    • Theme and situations
    • Drill down
    • Level up
    • There’s no perfect book or solution on this, but think about what works for your org

Avoid confusion!

  • Name your variables.
    • Avoid undefined “it”
    • No ownership
    • Vague terms
    • Unnamed ideas

Editing:

How we edit matters. We tend not to challenge deeper issues, and instead just hit minor technical issues, spelling errors, etc.

  • Editing is refactoring!
    • The goal is clarity, if you need to rearrange, cut stuff out, rewrite, don’t be afraid to.
    • Be an attentive reader, ask questions as you go. You don’t have to be an SME to be a good editor.

Q&A: Have you had any friction for getting into deeper editing?

I’ve been extremely lucky about that. Create a good rapport with that person, recognize that writing is often a personal thing and try to be responsive to that.

Q&A: Suggestion, another code idea: shared repositories!

Let’s make a shared set of useful documentation design patterns!

Q&A: Getting people to start improving rather than having to repeatedly do the same edits?

Guided questioning works really well, but it goes a lot slower. Peer edits are great, and a great spot to do developmental edits, explicitly.

Lightning Talks

Write Tight(er): Reiterating from last year: be mindful of be verbs! “be, is, are, am, was, has been, will be, will have been being” Why? You tighten up your writing, it becomes more engaging, and saves you money in translation cost.

Test the Docs!: Testing your documentation is a chance to also test your product, it creates paths to act as user stories. It gets you back to what users will experience. We’re not good judges ourselves, because we live with the product. Do company trades to pilot test your product, new users file different bugs than existing users, helps you identify the gaps in your documentation or new user experiences. We now write the docs first, give those to external partners and ask for feedback on what they’d expect. Lowers support costs, helps make better experience.

Open Source Documentation: The Hard Way: Half the documentation for OpenStack was written by 3 writers. And half again, by 7. The long tail was 130 contributors, little minor updates and changes and things. We treat our docs like code. We just did a book sprint: flew people in, collaborated, knocked out a 240 page book in a week (5 days). Created OpenStack Operations Guide. O’Reilly approached, they worked it out, and it’s now published by them. Worked so well that they sat down and did it again for the OpenSTack Security Guide.

Write, Measure, and Repeat: Trying to change how we think about knowledge management solution (works at Atlassian). Most systems don’t have any good way to gather metrics on effectiveness of our documentation. Started asking questions: can we lead people from software, to docs, and back, in an effective flow? Rewrote some tutorials to drive this idea, has been productive/worthwhile. Measuring at what points do people come into the documentation from software (and vice versa).

ePUB in a Nutshell: It’s a website, packed in a folder, with some xml. If you know HTML, CSS, and are somewhat comfortable with XML, you can do it. It’s portable, searchable, bookmarkable, and shareable. PDFs are made for print, not for sharing! How to learn? Find an ePub, unpack it (it’s just a zip file!). Documentation Dumpster Diving, is a good way to learn. @chuckdude

Documenting Domain Specific Knowledge – Alex Gaynor

Started writing docs for Django. They have a strong culture of documentation (likely related to the fact that the creators have degrees in journalism and english).

Why do people come to Django?

Existing Developers: Mostly looking for a reference doc. This is fine, and usually already know what they want.

New users: we still assume you’re not new to the web, just new to this tool. We choose to focus on our specific domain — learning Python is elsewhere.

Documentation is important. For instance, think about cryptography: it’s hard for users to know if they got it right, since the outcome is generally still gobbledygook to them. Good docs are important.

Can you write docs around a usability problem? Not really. So Documentation and Design need to work together. If you can’t write a clean tutorial, the usability is broken.

Pick an audience: this doesn’t mean “people who use my software”, this means thinking about what knowledge they’re come in with: are they already experts in related material, are they newbies, or what?

Straight-line Docs: nothing wrong with reference links and additional material, but if it’s essential, make it inline, not a link, and then cut out the stuff that isn’t directly relevant.

Make no assumptions: no jargon (or explained/defined if you do need to use it). Don’t assume known context. Punt not necessary things.

Be prescriptive: if you’re an expert and are writing the doc, don’t be afraid to provide actual recommendations.

Enable Use Cases: people probably came to your documentation to solve a specific problem. General purpose reference materials are useful, but solving specific user needs tends to be better to focus on.

Composition is great: connect the dots for the reader, solve real problems.

Get someone to test your documentation: people in your target audience that haven’t used the docs before. Any time they reach for Google or external docs? That’s a bug.

Always be improving

Give people easy wins: people are impatient, they want to solve a problem and get something done.

Don’t forget: users will never say “thank you.” That doesn’t mean they don’t value it, it just means they’re looking to solve a problem.

Q&A: When testing, is it really fair to omit external sources?

Fair, no, but it sets the bar for making sure we’re not reliant on other sources to be able to actually help our users.

Graphical Explanations – Geoffrey Grosenbach

Works for Pluralsight, creating tutorials and screencasts.

Information Anxiety: we no longer value information because it’s so ubiquitous. Instead, we’re willing to pay sources to filter and organize that knowledge.

We read things at different levels: skimming, flipping through, and actual reading. Think about this when writing docs. Graphics can provide a tool to allow users to consume your content at different levels and still find it useful.

If you want to read more about this topic, you should look up Edward Tufte. Also, Information Dashboard Design is another great book/reference.

Type

Typography also counts as a visual aid. It matters. The more you learn how to use type well, the better you’ll be able to communicate.

Useful: pull quotes, good titles and subtitles, color, using typographic memes.

Icons

Icons are handy, attractive, and often free. Examples, Symbolset, Symbolicons.

Explanations

Provide explanations! There are a lot of explanatory tools: “bad/good”, “problem/solution”, “before/after”, “good/better/best”, Compare/contrast, “Analogy”, Timeline.

In particular with longer guides, provide a hint of outcomes to start.

Teaching is difficult because learning is difficult. Taking the time to create multiple levels of understanding is worth the time and effort.

Minimum Viable Documentation – Matthew Lyon (@mattly)

What is a minimum viable product? Term gets thrown around a lot. Building software is expensive and risky. It’s about testing the feasibility of an idea before sinking more resources into it. “Build as little as possible”, a part of MVP, unfortunately often means docs get cut early because a lot of PMs don’t understand the value.

What is the purpose of software? Software helps solve problems. It needs to work better than existing solutions.

Personas can help developers identify what is needed. For example: As a “user” I want to “do something” so I can “be awesome.”

Getting the user’s world requires empathy. Figuring out what onboarding/support new users need is not the mindset developers tend to have. Need to ask “how are people going to interpret this interface?” Are we relying on conventions we’re immersed in to convey information?

Docs answer “What was I thinking when I wrote this two months ago?” Taking the time when it’s created can save a LOT of time later, totally worth the investment.

Pair with new developers to document difficult things as they have questions: this helps you find what the actual pain points are.

Reference documents are outboard memory, NOT a way to teach. Still necessary, but don’t call it enough.

Learn how to forget: personas, role playing, think as a new user.

How-To is the biggest bang for your buck: well worth the time to write. They work with user experience design, document the experience, and can also help inform if something is a little too confusing.

  • Link to HOWTOs in your marketing materials: show me how it’s actually easy to do what you claim it does. Link to HOWTOs from your new user experience, then track them.

  • Use your HOWTOs to regression test your user experience.

  • Use your HOWTOs to keep a handle on UX debt. If the tutorial is getting really long, maybe you’re accruing too much debt and should act on it.

In a lean environment, think of it like TDD: what if you thoroughly prototype your user experience by putting it into words?

Q&A: You mentioned prototyping, what are you using?

Paper prototyping is great, but has a weakness in that it forces you to rely on existing conventions, moving away from thinking about what you’re trying to DO, versus how you’re presenting it to them.

Q&A: Comment: one of our designers was talking about Documentation Driven Design. If you can’t describe what you want to do easily, it probably isn’t easy for users.

What makes good API Documentation – Lois Patterson

Good APIs -> Good API Docs

  • Consistent APIs make for consistent docs

Look at existing good API docs. Some developer favorites:

  • Netflix
  • Twitter
  • Github
  • Facebook
  • Paypal
  • Flickr

There aren’t really any API standards, but there end up being de facto standards that are probably worth following. You can see a variety at ProgrammableWeb.com

What’s good to have?

  • Description
  • Tutorials
  • Examples (an actual working app goes a LONG WAY)
  • Sandbox test environment
  • FAQs

Can also be good to have a reference page of related articles (example, Twitter’s “what pages link to Follow button” page)

What is helpful?

  • Clear versioning
  • Last verified date
  • FAQ
  • Working examples
  • Suggestions for using API.

Paypal has a good example of a test environment

Provide multiple avenues for developers discovering what’s been recently updated (Twitter, blogs, “recently changed” pages, et cetera).

Strategy for creating API Docs

  • Better to start writing and get corrected than to wait around.
  • If there’s a good design spec, that can be a good spot to start: building docs based on spec. Can help improve the spec, and gets you to a good starting point.
  • Work with the QA team, test cases are a great spot to start a user story or tutorial (and vice versa).
  • Once you’re at a minimally viable set of docs, get eyes on it, feedback is key to improving. If there is an internal customer, great source.
  • Think about the questions you want to answer with the docs: tell us about the API broadly, then start asking yourself increasingly detailed questions to answer.

@LoisRP

Documentation at Scale – Kenneth Reitz

Works at Heroku, also a member of Python Software Foundation, member of ~18 major projects, including OSX-GCC Installer, Requests library

Language

Early Humans: Alone with self & ideas, not many ways to communicate.

Spoken Language: express ideas to others.

Written Language: allows ideas to persist over time.

If you think about it this way, human hardware hasn’t changed much, but our software has definitely been upgraded.

Communication: One-to-One

At first, language was mostly used for a single person, to communication with another single person or small group of people.

Communication: One-to-Many

  • After the printing press, a single privileged entity could communicate to the Masses
  • Newspapers, books, television, radio, etc.
  • This formed the narrative of “the public”
  • Very polarizing — unifying but also destructive.

Communication: Many-to-Many

The internet!

  • If you have access to the internet, you have access to a universe of information and ideas
  • Anyone can publish anything to any number of people, large or small.

Information is Powerful:

  • Information is powerful — every day we see it transform the world around us.

Documentation at scale

  • Information architecture is a powerful tool for developing ideas over time and space.
  • It enables us to evolve and distill information

Read The Docs + Github == instant version-controlled documentation tool.

Python-Guide.org is an example of this workflow.

ReStructuredText is great, but unapproachable to laypeople. There’s still room for improvement!

Consider:

Internationalization, persistent archiving, reducing the bus-factor, fast revision merging, a policy of “being cordial”.

Q&A: How do you create consistent tone with lots of contributors?

It’s not great right now. Establish style guide, and then taking time every so often to clean it up as an editor.

Q&A: Do you have a process for review in pull requests?

Create minions: trusted contributors that you feel get the goals of the docs. At first, it’s fine if it’s just you, but recognize when you’re starting to be a bottleneck.

TechDocs, Creating a Culture of Documentation at Twitter

Goal: “Make Twitter a Learning Organization”

Twitter acquired a training company because they wanted to encourage learning and education at Twitter. Presenters came from that company, which was focused on training/education. Since they were already doing training docs, they ended up also taking over technical writing, which was not originally their focus.

Created a survey of the engineers at the company, asking how they felt about internal docs.

  • The answer was depressing: most hated the internal documentation.
    • Part of the survey also included a plain-english comments section asking why: the recurring words that kept on coming up were “stale”, “doesn’t exist”, “too hard to find”.
    • Needed to work out a solution for solving these pain points.

Problem: 1000+ engineers, 3 tech writers, all of whom were already fully allocated.
Solution: Tech writers do some writing, some oversight, and engineers write docs!

This requires a culture shift: code already has to pass code review, and gets rejected if it doesn’t have tests. We’re now requiring at least minimal documentation as well.

Technology: when you get to a certain size, you inevitably need to create something like Read the Docs, but internally. Ours is called DocBird. It’s built on top of a git repository and plain text documents, which are parsed using ReStructured Text to generate HTML docs (a modified version of Sphinx). They also made a tweak so it could also support markdown in addition to RST.

The point of this switch away from the existing wiki (confluence) is:

  1. Wikis are terrible for managing documentation.
  2. The wiki was seen as “someone else’s problem”, and engineers didn’t update it.
  3. By moving the docs to a git repo that lives next to the actual code, and acted like code, engineers didn’t have to try and adjust to a different workflow — it was a flow they already understood and used/preferred.

Created a framework/stack: DocBird + Templates + DocDays (a day set aside every other month or once per quarter where the team would agree to dedicate towards making sure their own documentation was up to date).

Another problem faced was: Where were the existing docs? The answer was: scattered all over the place. Some were in the wiki (>60k pages, >150 team spaces), others were in Google Docs, some were simply markdown/text files sitting next to the code.

Solution:

  • Slowly migrate more and more into DocBird, but in the short term, require teams to at least maintain a readme/list of where else all of their documentation is, stored in DocBird.

Goal of the current effort is: Treat Docs Like Code:

  • Checked into Git
  • Plain Text
  • Reviews and Merging.

This is great for engineers, but harder for tech writers. Made this tradeoff because it made more sense to accommodate the larger population and encourage engineers to write. Still working on making it easier for non-engineers.

Hit a few roadblocks with this implementation:

  • ReStructured Text: some people roll with learning a new markup system, others were REALLY unhappy about it. Hacked together a markdown parser to appease.
  • API Docs: This is its own animal, with its own problems, but is often requested.
  • Language Support: Twitter is a poly-language dev environment, and Sphinx/DocBird only supports so many languages. Python, sure! C++, alright. Scala? Are you serious? Et cetera.
  • Not a wiki: despite devs never updating the wiki, as soon as we moved to a new system they actually update, they asked for an online editing method like a wiki.
  • Feature Requests: A lot of good ideas, but a lot of work to implement with limited resources.

Continuing to update DocBird helps some, but still bump into edge cases.

Measuring the Impact:

  • How in sync are the docs with the code?
    • Checking drift between the two is easier to note in Git, since you can see revision histories for each file, and can more quickly notice that there have been 40 commits to a code file when the doc file hasn’t been touched in the same amount of time, meaning it’s likely no longer accurate and should be checked.

It’s helped to think of TechDocs as an agency:

  • Everyone was already fully allocated, time-wise.
    • Had to push back, carve out 20% time for broader doc improvements.
    • Shift mentality away from contract-like, more towards consulting/agency.

A big problem is “no docs”, but there is also the problem of confusion. Need to enforce consistency in formatting, style, locations.

Having everyone in the same documentation platform gamifies docs — it also shames teams with no documentation into actually writing some docs.

Measuring normalization:

  • How consistent is the UX for docs across the entire organization?

Next steps: Shift the culture: things like DocDays helps make documentation the “new normal”

  • Better tech alone won’t create a culture of documentation, needs buy-in from leaders and examples to be set.

This is a work in progress: we’re still in stealth mode within the company: there’s been no mandates or pressure from upper management yet. Despite this, we still get engineers coming by, excited about getting involved and wanting to write docs. This is really encouraging.

Convincing Engineers to write:

  • Set a mandate of including docs with code commits.
  • Encourage by explaining how others will be more likely to use (internally and externally) code that is well documented and easy to get ramped up on.

Measuring improvement:

  • How happy are users?

Start with carrots… but also have sticks if you need them.

@TechDocs

Q&A: Is the new platform worth the work of moving off the wiki?

Devs view the wiki as a separate thing, not their problem. Moving it to a repo changes the view.

Q&A: how are you handling information architecture?

We have it broken into projects, and then are normalizing expectations and terminology.

Note: Short notes for the last few sessions because my laptop battery died and I wasn’t near a plug, so the rest were by hand. Will pull up slide decks as I gather them. There are also some EXCELLENT write-ups over at http://andrewspittle.com.

Say More With Less: Writing for a Global Audience: Write Global, Win Local

Maxwell Hoffmann (@maxwellhoffmann), Adobe Product Evangelist

  • We have smaller screens
  • Shorter chunks of content
  • Shorter attention spans

We can all benefit from ASD-STE 100 standard for simple English — this helps a lot if you need to translate your docs, but it’s also useful for making more effective writing in general.

  • One Line per sentence!
  • Use valid nomenclature!
  • Don’t use gerunds! (“ing”)

Data, Documentation, and Memory

Amelia Abreu

Started as an archivist, ended up in UX. The archivist background still informs her work.

Planning to discuss relationship between:

  • Documentation and Work
  • Documentalist Movement
  • Documentation, Metadata (and Meta Documentation)
  • Information architecture

What do we document?

And equally important, what don’t we document?

Look into the Cognitive Organization Analysis that came out of the 50s. Looks kind of like an onion, with layers, and documentation at its core. Came out of a desire to detail the work involved as a nuclear engineer.

We end up doing ethnographic interviews, seeking out the not documented, sussing out the hidden details.

Madame Documentation

  • Spearheaded the Documentalist Movement
  • Documentarian in France from 1920s to 1950s
  • Wrote “What is Documentation”, a short (80 page) book that you can download for free online as a PDF. Well worth the time to read.

It can be worthwhile to focus on processes when you need to, but also pay attention to your artifacts.

Death by Documentation – Christina Elmore

Cares deeply about the art and science of presentation. This talk is to discuss the important difference between documentation and presentation.

It’s not that documentation is damaging presentation, but there is some serious conflation between the two, and it blurs the details from both, making both less effective.

Documentation

  • Self-guided
  • Meant to be read

Presentation

  • Presenter Guided
  • Meant to be heard/watched.

Good presentation slides are bad documentation!

Try to ignore that itch to turn slides into your documentation, and to dump in more information than you need. It’s a disservice to both.

How Will I Remember What to Say?

  • Ask yourself: who really matters? Not you. The Audience.
  • Create a story structure to your presentation.
  • Rehearse!
  • Story Structure + Rehearsal = Retention.

What Will I Share In My Presentation?

  • Check out Matt Haughy’s guide to better presentations.

What If I’m Not Here to Explain?

  • Documentation != Presentation!
  • Record your presentation if necessary.
  • A presentation is not MEANT to stand on its own, so stop trying to make it.

One idea is to eliminate the presentation from meetings entirely. Several companies (LinkedIn, others) no longer have presentations during meetings. When a subject comes up that would be presented, it’s documented, and those materials are circulated. They spend the first 10 minutes reviewing the docs, then spend the rest of the time that a presentation would have happened having an actual discussion about the material.

Look into SlideDocs, a lot of great resources about this.