WTD CONFERENCE PORTLAND (OR) 2016: talk summaries and video recordings

Eric Holscher: Introduction & State of the Docs



WTD as a community:

  • Growing: 400 ppl in Portland; 250 ppl in Prague

Documentarian:

  • Expand and evangelize documentation to other groups so that they learn to care about documentation.

Future of WTD NA:

  • Maybe need to split to West Coast and East Coast conferences because there are so many attendees.

Britta Gustafson: Technical writing as a public service: working on open source in government



Federal government & digital services

  • open APIs and open data, helping you file your taxes, transforming payroll to be free
  • uses human-centered Agile, iterative, open source (FOSS)
  • People should be able to see what the government has spent taxpayer money

Public service + open source + documentation = of the people, by the people, for the people

Content Design: generalist writer role, that includes: content strategy, interface copy, docs, blog posts, info architecture, etc.

Neal Kaplan: Two Great Teams that Work Better Together: Bridging the Gap Between Documentation and Customer Support



Customers and Documentation

  • Happy customers = more sales
  • A happy customer will:
    • Renew subscriptions
    • Buy Products
    • Provide feedback

Information sources for documentation

  • Support ticket reviews, check customers’ terminology, ticket metrics → trends



Tech writers and the support team should join forces.

Allison Reinheimer Moore: So You Need to Document an API?



API documents are all about answering questions

  • Documentation types:
    • Conceptual
    • Tutorial
    • Reference
  • Take stock:
    • Who are your users and what are their motivations?
    • What do users want to do with the API?
    • What does the API do?
    • Which programming languages are popular among your users?

Shaun McCance: Crossing the Streams: Enabling Collaboration Between Product and Upstreams



Red Hat: everything is open-source

  • Make upstream docs reusable by downstream users

Make upstream docs:

  • Think in topics
  • Use tasks to explain how to accomplish a goal
  • Working with community
  • Analyse your audience



“Every page is page one. Do not assume the reader will read your doc in order.”

Sarah Day: Copy That: Helping your Users Succeed with Effective Product Copy



Best practices:

  • Every text element in the UI should have a predetermined purpose
  • Writing is easier when you have a system
  • Product copy is heavily contextual (be specific)
  • Help your users make choices
  • Button content should begin with verbs



The user experience is more important than the company's business drives.

Daniel Beck: Write the Readable README



Context of a README:

  • What kind of project is this?
  • What other files accompany the README?
  • Which markup is this?

Content of a README:

  • Which topics does it include?
  • Which links and images are in the file?
    • Information readers need to know, visual impressions



The best READMEs give you confidence about the project even if the README does not answer all your questions.

Tana Franko: Continuous Annoyment: Bringing More Zen to a Hectic Writing Environment



  • No problem can be solved from the same level of consciousness that created the problem.
  • Continuous Annoyment: state of mind filled with many small problems that add-up to a bigger problem.
  • Balance problems with solutions. Looking at too many problems and too many opposing forces at once, led to simplifying things.



Problem > Challenge > Opportunity

Kristof Van Tomme: Embed The Docs!



  • Documents need to address the erosion of end-user attention
  • Documentation ≠ Manuals



Documentation can be in the user interface (UI) rather than a manual.



Improve the UI with:

  • Microcopy
  • Popups in the UI
  • Walkthroughs, guided tours such as walkhub.net
  • Help Centers, get help on websites, contextual info such as embedthedocs.com

Tracy Osborn: Writing So Your Words Are Read



How To Write Better Docs:

  • Your readers are not you. Write for their experience, not yours
  • Do not write like a machine. Use friendly, easy to understand vocabulary
  • Create a persona and write for that person
  • Use gender-neutral language
  • Do not forget to use headlines: short, easy, simplified headlines that benefit the reader



Simplify your content whenever possible

Panel talk: Transforming your Documentation Process



Moderated by: Riona MacNamara. Panel members: Leon Barnard - Zach Corleissen - Ted Hudek - Jon Bulava

How Twitter, Microsoft, Rackspace, and Balsamiq write the docs.

  • Importance of open-doc culture.
  • Why the docs are separated from the code?
  • The role of the content creators is changing.



Interesting perspectives about the documentation problems that were solved, tools to solve the problems, and internal cultural changes.

Ruthie BenDor: Move Fast And Document Things: Hard-Won Lessons in Building Documentation Culture in Startups



How to write internal docs at fast-moving organizations:

  • Figure out what is broken (dig into the issue, solve the problem, analyze the issue).
  • Figure out why your organization will care about fixing whatever is broken.
  • Couch your solutions in the organization's values.
  • At every inflection point, reevaluate, rinse, repeat.

Christy Lutz: We Are Not in Kansas Anymore: How to Find Courage while Following the Technical Doc Road



Talk to your team about documentation

  • Your team are the QA, DevOps, Tech Support people that you speak with everyday for help with documentation.

Be vulnerable:

  • Willingness to be wrong in public
  • Be open and honest when you give/get feedback
  • Compromise
  • Collaborate with your teams.

Make plans & practice sharing all the time



Nothing is perfect.

Betsy Roseberg: CSAT – What’s That?



CSAT = Customer Satisfaction

  • Use customer comments to improve your documentation.

    • When customers provide useful data, research it, confirm, and then improve the documentation.
    • Use the customer data to update documentation.
    • User comments can be used to clarify your documentation, even if the doc was technically correct.



CSAT is an absolute necessity to determine if customers are satisfied.

Brianne Hillmer: Just-In-Time Documentation: Employing Agile Methodology



Just-In-Case Documents:

  • Feature guide, easy place to start, helps users learn about features, but doesn't solve problems for customers.
  • Difficult to use and search.
  • Requires familiarity with terminology.

Just-In-Time Documents:

  • Manufacturing production strategy, cost effective, produce and ship products based on customer needs.
  • Create documents when customers need documentation.



Learn about the user’s needs.

Tim Nugent & Paris Buttfiled-Addison: Code The Docs: Interactive Document Environments



  • Code + Docs + Notes
    • Helps the user by putting the code, documentation, and user notes in a readable format, in one place.
    • Swift Playgrounds
    • IPython Notebooks
    • Project Jupiter
  • Strengths
    • Code, documentation, and user's notes are together on-screen.
  • Weaknesses
    • Only Markdown and HTML

Sharon Campbell: How To Publish Wild-Caught Articles



  • Why people write for communities:
    • Share expertise.
    • Work with an editor.
    • Get published.
  • How does DigitalOcean find authors:
    • Social networking, blog posts, DigitalOcean community writers.
  • Screen the authors before you hire:
    • Technical expertise, writing ability, personality.

Tim Arnold: Accessible Math on the Web: A Server/Client Solution



Use Equations in Documentation

  • Software
    • La Tex, MathML, MathSpeak, MathJax
  • Accessibility
    • Zoom for users with low-vision
    • Screen readers for blind people
  • Render equations
    • There is limited browser support for Chrome and IE, Firefox supports equations.

Tara Scherner de la Fuente: Oops, I Became an Engineer



  • Technical writers can improve communication with developers
    • If you can reduce the number of meetings developers need to attend, then it is easier to get developers to meet with you when you need them.
  • Learn software development
  • Learn how to code
    • Find a method that works for you, might need to try several learning methods.



Expect failure.

Hannah Gilberg: Documentation with Human Connection



Ways to Improve Human Connection

  • Write, revise, and review documentation to make it more engaging.
  • Business Problem: created a lot of documents, but not a lot of communication because people were not reading the documents.
  • Be specific, concrete, and precise in your writing.



Good writing is more than adhering to rules, it is about connecting with the reader.

Daniel Stevens: Atlassian: My Information Experience Adventure



  • Build a culture where information is a critical part of the experience.
  • Combine design, research, data analytics and technical writing.
  • Information Experience (IX):
    • Gather data.
    • Set a direction (content strategy).
    • Measure results.

Thursday Bram: What Writing Fiction Teaches You About Writing Documentation



We can bring elements of fiction writing to documentation and improve the documentation.

  • Clever is rarely clear; clarity is crucial to the reader.
  • Providing context is critical; use links to direct the reader to more details.
    • Set a reading order (recommend it to your readers).
  • Use beta readers.
  • Read as widely as possible.
  • Write everyday.

Joao Fernandes: Seven Values of Effective Tech Writing Teams



1 Be the CEO of documentation.
- Define a vision.
2 Pitch your vision.
- Drive your vision, make it happen.
3 Understand the market, product, and users.
4 Ask why?
5 Be proactive.
6 Treat words as tools.
7 Coach others.
- Help others to create documentation, share your knowledge.