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.