↓Skip to main content

Highlights from the 2019 Write the Docs conference in Portland

Introduction #

I was fortunate to be able to attend Write the Docs Portland this year for the second time. I always get a ton of value from the conference sessions and the fellowship with other writers. Here are some notes and links that I hope you find helpful.

Common themes #

  • sense of community and overcoming isolation
  • learning how others solve problems
  • industry best practices
  • latest research and solutions
  • the surprising value of lightning talks

Writing Day notes #

Writing Day tables #

On Writing Day, there were a multitude of tables set up to discuss various topics. Here are the tables that I spent some time at.

  • Tensorflow version 2
  • Microsoft
  • Netlify CMS docs; making forked repo CMS work
  • Cockroachdb
  • Mike Lewis - GitLab docs as code; GitLab Pages
  • Dan Allen - asciidoctor open source
  • Marty Avidon - Wikimedia
  • ST Cohen - IA
  • Anita - drawing scenes

Antora / AsciiDoc tables #

I spent a lot of time here. OpenDevise and Antora are doing some amazing things. Here are some links to get you started.



Presentation notes #

Loving the CLI #

Mike Jang



Documenting for open source software #

Shannon Crabill

https://shannoncrabil.com/writethedocs

  • incomplete or outdated docs are a pervasive problem, observed by 93% of respondents https://opensourcesurvey.com
  • avoid assuming the technical proficiency of your readers
  • put the effort into your README file
  • include a code of conduct
  • solve for duplicate pull requests - create pull request and issue templates
  • use GH tags intelligently
  • have a good changelog
  • leverage / link to other helpful docs
  • anyone can contribute to open source



Writer? editor? teacher? #

Kathleen Juell at Digital Ocean

  • create docs with the right level of access
  • empower users to ownership of ideas and methodologies
  • empower users to create cool stuff with technology

What can we learn from related fields?

Statement of teaching philosophy

  • your conception of teaching and learning
  • a description of how you teach
  • a justification for why you teach that way

Teaching in your intro (e.g. tutorial)

  • provide users with necessary context and definitions
  • frame the why
  • explain the how

provide context and background

  • define
  • justify
  • outline

complex content: see the book “Understanding by Design” re: K-12

  • explain general principles where possible
  • reference different contexts and scenarios where possible
  • gauge your audience
  • say why

Editorial templates

  • packaged, reproducible suggestions
  • prewriting
    • what is this tutorial about?
    • why should the reader learn this?
    • what will they have accomplished?
  • writing
    • discussing large code blocks and commands
    • tell the reader what code will do, first
    • after, explain some of its key concepts

Peer editing as teaching

  • explain your thinking
  • treat grammar like a high-level topic
  • ask questions

Write like a teacher

  • clarify your why
  • have an understanding goal
  • explain your own thinking to yourself



How to edit other people’s content without pissing them off #

Ingrid Towey at Red Hat

We’re all on the same side

  • customer side
  • don’t argue
  • some things are true for all customers
  • people form a lasting opinion of your site in 50 milliseconds (1/20 sec)
  • you have at most 10 seconds before users leave your website
  • you have up to 60 secs if your site is already trusted
  • they read 28% of page content
  • net: customers scan, not read

Edit, not edict

  • not a tennis match
  • no passion equals the passion to alter someone else’s content
  • make your edits reversible
  • she edits for 124 writers

Explain why

Resources

  • Flesch-Kincaid Grade Levels
  • readable.io
  • Hemingway editor
  • Microsoft Word
  • Acrolinx
  • IBM style guide
  • MicroSoft style guide
  • Google style guide
  • minimalism
  • DITA guidelines for modular docs
  • usability testing
  • nielsen norman group articles

Get help

  • peer review
  • group editing

Be kind

  • Toastmasters
  • positive, negative, positive feedback sandwich
  • have a meeting leader
  • it’s all about the relationships
  • assume positive intent



Making friends of the docs #

Heather Stenson

How to make friends of the docs

  • team leads are a great resource. face to face time at least quarterly.
  • share product feedback - good or bad!
  • tie documentation to the bottom line
  • bribery (stickers, shirts, food, happy hours)
  • use the processes that are already in place (find and leverage)
  • create a docs-specific global channel
  • create a docs issue tracker
  • create ‘friends-of-the-docs’ badge and be able to communicate with all at once

Obstacles

  • silos: open up your own silo, first
  • become a bridge between silos
  • widespread corporate docs obliviousness
    • have docs team be very vocal and visible
    • reach out proactively to other teams
    • every thing you do must demonstrate that “we are a company that values documentation”

Everyone is too busy

  • spend time now to save time later
    • support writes a tutorial that saves a bunch of time handling customers opening tickets
  • helping -> response -> satisfaction loop

Maintaining this is an ongoing process

  • model behaviors that you want to see
  • loosen your grip a little
  • set boundaries and parameters, guard rails
  • help the helpers
  • keep things fun and FRIENDly
  • swag, give public appreciation
  • appreciate people
  • stay friends when the team relationships change

Don’t:

  • be a jerk
  • take people for granted



Defying the Status Quo #

Jodie Putrino at F5 Networks

https://clouddocs.f5.com

Process was:

  • DITA
  • reviews from annotated PDF
  • waterfall
  • ineffective review process

Defiance

The process is not the thing. It’s always worth asking, do we own the process or does the process own us? –Jeff Bezos

Now:

  • simple markup language
  • GitHub PRs
  • Agile process
  • CI/CD, a.k.a. Docs as Code

See her 2017 presentation:

Influential sessions:

Success factors

  • helping others
  • fierce advocacy
  • don’t take it personally
  • be patient
  • have rabbis

You are the best advocate for your project.

Status quo is the biggest threat for companies, culture, personal growth - Francois Loc… F5



Lessons learned in a year of docs-driven development #

Jessica Parsons at Netlify

Write the docs first! Build to match.

You can include user stories or specs, but there’s more to it than that.

This is not waterfall all over again.

Iterate.

How were they successful at this?

  • strong leadership support
  • docs valued in the org
  • generally good communicators

Lessons

  • good intentions are not enough

Tips on making this happen

  • provide scaffolding (term from educational psychology)
  • think beyond the written word: diagrams, wire frames, video
  • designate a leader to drive success (perhaps rotate)
  • make sure your work counts (see Tanya Reilly’s talk on Glue work)
  • Identify issues when investment is low
  • devs adjust plans as they write
  • writers spot issues that spark conversations
  • leverage team expertise
  • add accountability - reviewers and time lines
  • notify people about changes
  • look at Notion tool (doesn’t solve all problems)

Good docs enable:

  • reducing impostor syndrome
  • parallel execution
    • example: front-end developers against API spec while API devs build the endpoints
  • support learning about features in advance
  • marketing can prepare for launch

Docs-driven doesn’t guarantee “user-centered:”

  • beware function-focused user stories
  • get users involved sooner
  • enlist customer-facing teammates

School is still in session.

Docs or it didn’t happen -> docs or it won’t happen.



Show Me the Money: How to Get Your Docs the Love and Support They Deserve #

Matt Reiner

  • SWOT
  • map your goals to the long-term plan of the business
  • elevator pitch, the what and why
  • internal marketing. the seasons when this is important in your company.
  • find friends in sales and marketing
  • sales controls the perception of “what the product does”
  • support is a huge focus these days
  • marketing, sales, and support
  • competitor analysis

Build the business case

  • need metrics and data
  • overcome exec’s gut feeling that docs are a waste of money
  • support deflection rates
  • your friends have data that can help you
  • be helpful and practical (you don’t have to know everything)
  • influence others - don’t bulldoze
  • assemble your plan. draft. collaborate. present to friends. iterate.

Write the product plan - whole enchilada with details Financial Plan - get help



Just Add Data: Make it easier to prioritize your documentation #

Sarah Moir

Splunk - big data analysis

  • prioritizing docs is hard
  • use data to build confidence in decisions
  • challenge or validate assumptions



Drawing in technical communication #

Alicja Raszkowska

See: Mermaid software



Lessons learned at the conference #

  • The value of our community
    • writers sometimes find themselves isolated
    • connectedness
    • solidarity
    • esprit de corp
    • the richness of face to face conversations
    • the impact of social setting on conversations
  • building relationships
    • the collaborative value of un-conferences
  • the business value of content
    • expertly presented by Matt Reiner
  • the Doc-Ops revolution
    • frictionless interaction with tools, frameworks, and platforms
    • increases productivity
    • make changes often without breaking systems
    • move with speed SRE concept: short lead time. reduce feedback latency.
    • developer experience
    • automated doc testing
  • the increasing use of Git and GitHub, GitLab, etc.
  • the value of learning the latest documentation best practices