pre-release: Eric meeting announcement
Please take a moment to review your details and reply with OK or edits.
Subject and below is what will go out and also will be used to title the videos.
Subject:
ANN: Eric at Room 1 Mon April 8, 9:15p
Eric
=========================
When: 9:15 AM Monday April 8, 2013
Where: Room 1
Write the Docs is a two-day conference focused on documentation systems, tech writing theory, and information delivery.
None
Topics
------
1. Documentation is King
Kenneth Reitz
Documentation leads to better code.
Every design decision should be documented. Imagine not having to have tap your coworkers on the shoulder when you’re working on an unfamiliar part of the codebase, or on-boarding a new employee. Imagine being able to make the change, run the tests, and push to production without questioning yourself, because the process was documented — or better yet, automated.
recording release: yes license:
Video: http://videos.writethedocs.org/video/1/documentation-is-king
2. How Mozilla supports users all over the world
Michael Verdi
The Mozilla support platform is built around a fully localizable wiki and an awesome community of volunteers. Together we’re able to support nearly half a billion users in dozens of languages. This talk will focus on how we support the 50% of Firefox users who use it a language other than English.
recording release: yes license:
Video: http://videos.writethedocs.org/video/2/how-mozilla-supports-users-all-over-the-world
3. Beautiful Documents - A Language Love Story
Erin Robbins O'Brien
Technical writing, content marketing, and all other forms of documentation are a love story between writer and document. Carefully walking the balance between attractive, desirable content and the stability and comfort of getting the information needed. This talk will poetically address how to re-kindle your document love if it has been lost, and some strategies to keep the fires burning so you each document you write is as exciting as the first.
recording release: yes license:
Video: http://videos.writethedocs.org/video/3/beautiful-documents-a-language-love-story
4. Typography for Docs
Matthew Butterick
Should writers of documentation care about typography? As someone who reads a lot of documentation, I can see that many don’t. But good typography can reinforce your meaning, conserve reader attention, and make your docs more inviting and useful. And it’s easier than you might think. In this session I’ll explain the four rules of typography that every writer of docs needs to know. I’ll also cover some typographic issues specific to web-based docs, and critique a few real-world examples.
recording release: yes license:
Video: http://videos.writethedocs.org/video/4/typography-for-docs
5. Evolution of the English Language from Text to Texting
Sarah Grant
Or, Why the Oxford English Dictionary is My Favorite Book, and Why I Love the Chicago Manual of Style
The Oxford English Dictionary holds the key to every word in the English language, starting with the language from which it was borrowed/stolen, following its history to current times, and giving examples of usage from the beginning. New words are introduced into common usage every year, and some make it into an official dictionary. Some words are practical (i.e., Internet), while others are superfluous (i.e., ironical) and many are just plain wrong {i.e., orientated).
The “correct” use of words and language seems to be more and more fluid these days. Will commonly used acronyms, seen mainly in texting and instant messaging, become part of the standard usage? How fluid SHOULD the English language be? What types of grammatical and punctuation changes are acceptable, and what types are not? Where do we draw the line?
This talk will present these questions and others, and begin to formulate possible answers to benefit the potential audience of writers.
recording release: yes license:
Video: http://videos.writethedocs.org/video/5/evolution-of-the-english-language-from-text-to-te
6. Motivating developers to write API documentation
Jennifer Hodgdon
Everyone attending this conference probably agrees that it’s a benefit in any software project to have good API documentation. But how do you get it written? There are three possible strategies: (a) Developers write the API documentation, (b) Technical writers write the API documentation, and (c) No one writes the API documentation. Option (c) is obviously undesirable, and option (b) is only viable in a corporate setting, so in open-source, the question becomes: how to motivate developers to write good API documentation.
In the Drupal open-source project, API documentation has become one of the “Core Gates” that (in theory anyway) all patches must pass through to get committed to Drupal Core, which has taken API documentation from being an afterthought to being a requirement. This talk will go over:
The "Core Gates" concept and how it came about
The requirements for the Documentation "gate"
The Drupal project’s documentation standards
How it’s working in practice
recording release: yes license:
Video: http://videos.writethedocs.org/video/6/motivating-developers-to-write-api-documentation
7. Lightning Talks - Monday
https://write-the-docs-2013-notes.readthedocs.org/en/latest/monday/lightning-talks.html
0:0 Daniel Beck - A Plea to Open Source Maintainers
4:32 Carlee Potter - Writing User Guides
9:44 Bart Massey - The X.org Virtual Book Sprint
14:40 Eric Redmond - FAQs: Stop the Cargo Cult
recording release: yes license:
Video: http://videos.writethedocs.org/video/15/lightning-talks-monday
8. Generating a Culture of Doc
Leah Cutter
How do you encourage engineers to do the write thing? (Not a typo.)
At Salesforce.com, we now have a team called, “Core Documentation.” We are primarily focused on documenting our internal systems and architecture. Many of us on the team don’t create content: We generate framework, best practices, and training for engineer-created content. (Content can include and is not limited to: code comments, run lists, specs, team web pages, wikis, white papers, architectural diagrams, presentations, etc.)
But that goes back to the first question–how do you get someone to write, when the word “writer” isn’t part of their title?
We’ve been successful using several different venues: - Documentation “hack” day – where engineers spend a day improving their internal doc - Events where posters of different aspects of the architecture are displayed (think art walk, only for engineers) - VERY easy to use templates for readme files, etc. - Lunch meetings/presentations/training/networking - Flattery, appeals to logic (bus factor) and bribes
Plus I would also present some of the things that haven’t worked.
recording release: yes license:
Video: http://videos.writethedocs.org/video/7/generating-a-culture-of-doc
9. Getting Developers and Engineers to Write the Docs
Kevin Hale
At Wufoo, everyone has to wear multiple hats in our company and that includes manning the inbox and doing customer support every single week. One of the interesting side effects of having a company where designers, developers and even the accountant writing documentation and answering support emails, is that everyone has a stake in making sure the application is as easy to use as possible.
We’ve called this approach to creating software Support Driven Development and in this talk Kevin Hale, one of the founders of Wufoo, will share how this model transformed every member of their company to be dedicated to the principles of clarity and simplicity.
recording release: yes license:
Video: http://videos.writethedocs.org/video/8/getting-developers-and-engineers-to-write-the-doc
10. Translating Customer Interactions to Documentation
Nisha George, Elaine Tsai
If customers have problems they can’t find answers to or need to report an issue then they contact your Customer Support team. Support is first line of defense to keeping your customers happy. But, customers are happiest when they can find answers on their own without having to wait for a response from Support. When Support owns a portion of the docs: customers are empowered to find solutions on their own, the incoming volume of tickets reduces and companies can better scale their internal teams in relation to their growing customer base.
This presentation will cover the types of documentation that your company’s Support team should own along side the documentation maintained by Engineering. We will give examples of how your Support team can:
Turn incoming tickets into FAQs to prevent future tickets
Provide answers for all types of customers, from beginners to experts
Create positive experiences for customers and internal teams
recording release: yes license:
Video: http://videos.writethedocs.org/video/9/translating-customer-interactions-to-documentatio
11. Technically Communicating Internationally
Teresa M Talbot
Ever dreamed of working abroad? Often overlooked as an international career, technical documentation has taken me to nine countries and allowed me to work with many of the world’s cultures. Truth is, if you’re translating it’s best to start with English. More people speak English as a second language than any other and, as you want translators to translate into their first language, it’s easier and cheaper to translate from English. Come hear and share international experiences. Learn why and how I managed it legally. Gain tips and tricks for getting what you need from subject matter experts in a foreign (to you) culture and writing with translation in mind. Cultural shocks and embarrassing moments? I’ve got them and can help you avoid them.
Countries where I’ve lived and worked:
USA
United Kingdom
New Zealand
Netherlands
Japan
Bulgaria
Spain
Switzerland
France
recording release: yes license:
Video: http://videos.writethedocs.org/video/10/technically-communicating-internationally
12. The Unenviable Tutorial
Daniel Lindsley
It’s the first thing every new user looks for, the raison d’être of every project, almost always will completely divide the people evaluating your software & is the leading cause of liver cancer in the American pub... wait, no. Forget that last part. What I’m talking about is the Tutorial.
Frequently the first bit of documentation written, the first one to fall hopelessly out of date & the one everyone sees, the Tutorial bears the brunt of getting people started. Its job is to pull people in. It teaches them not only what the software is about, but how it should be used. It sets the stage, the standard & the lowest bar of entry. It’s unenviable because it must do so many things & do them well to be a success.
recording release: yes license:
Video: http://videos.writethedocs.org/video/11/the-unenviable-tutorial
13. Single Page Docs: Stop the Click Insanity
Brandon Philips
Multi-page docs are the norm in most documentation framework. However, they aren’t the best tool for the job of creating usable docs.
Take for example the docs found on readthedocs.org for Django Fluent Contents. This is a very normal looking sphinx project. Now lets try to find example code for the announcementblock plugin:
Ctrl+F “announcementblock”. Darn, ok, no results.
Ctrl+F “plugins”, Nope, Enter, Nope, Enter, Enter, Enter, Enter
Click on the link for example code, there it is! Woo!
This style of code docs forces users to guess, click around, or simply leave your docs and use a Google site: search.
A better alternative is single page docs like those for Express JS. In this talk I will explore the best patterns and tools for single page documentation. And also explore the features and niceties that take single page docs from good to great.
recording release: yes license:
Video: http://videos.writethedocs.org/video/12/single-page-docs-stop-the-click-insanity
14. Why Projects Should Have “What’s New” Documents
Andrew M. Kuchling
Describes the speaker’s experience writing What’s New documents covering the new features in each Python 2.x release. The editorial policies will be summarized, and the speaker argues that large projects should include a “What’s New” as part of their standard documentation set.
recording release: yes license:
Video: http://videos.writethedocs.org/video/13/why-projects-should-have-whats-new-documents
15. Write Tight(er)
Marcia Riefer Johnston
http://howtowriteeverything.com
This presentation helps technical writers transform text into specimens of conciseness. With small screens squeezing the “page”—and with translations costing around $0.25 per word per language—this timeless skill gets more and more timely. Attendees will learn:
How flabby writing hurts business.
Why “concise” does not equal “short.”
Why they don’t need a double-standard to write for small screens.
How to tighten and energize their writing.
recording release: yes license:
Video: http://videos.writethedocs.org/video/14/write-tighter
16. Text Lacks Empathy
Noirin Plunkett
Have you ever written a nice friendly email and gotten a reply that seems like they read a whole different email?
In Open Source communities we write to each other all the time, but we’re not really writing, we’re speaking with our fingers. Text is our primary way to communicate, but text has problems. Speaking conveys subtle emotional cues that as social animals we rely on; text strips them out. A thoughtful correspondent can put those emotions back, but we’re often not thoughtful.
This talk is about the special problems of textual communication: mitigating them; ensuring that what you mean to say is what is understood; interpreting messages that seem totally out of whack; and increasing empathic bandwidth.
recording release: yes license:
Video: http://videos.writethedocs.org/video/16/text-lacks-empathy
17. Translating Science into Poetry
Daniya Kamran
Whether you’re writing a grant, putting together a speech, giving a lecture, or conducting any sort of expression through a document, you’re asking the reader to respond to a narrative. Especially when you’re dealing with subjects like science, technology, education, or business, developing a compelling narrative can be increasingly difficult. Technical writers deviate from risky narratives because too much of their readership is focused on professionalism. What is unnecessary? What is “flowery”? What makes you comes across as less of a scientist? This talk demonstrates how to extract narratives from technical documents by utilizing lessons learned from poetry, and especially focus on using these narratives to create compelling supplementary documents from scientific data, such as infographics, talks, or impact assessments
recording release: yes license:
Video: http://videos.writethedocs.org/video/17/translating-science-into-poetry
18. Versioned Literate Programming for Tutorials
James Tauber
This talk will explore the authoring of programming tutorials where each step of the tutorial involves code snippets that build on the code presented in earlier steps.
Because such tutorials are primarily exposition in human language, but contain code snippets that should be executable if extracted, the approach has a lot in common with Literate Programming.
At the same time, because the tutorials effectively guide the reader through the construction of the code, step-by-step, there is also a lot in common with Version Control.
Hence I describe this approach as “Versioned Literate Programming”.
I don’t (yet) have a good toolkit for this sort of tutorial authoring and so the talk will mostly focus on the ideas and challenges involved as well as some of the different approaches I’ve attempted over the years of thinking about this.
recording release: yes license:
Video: http://videos.writethedocs.org/video/18/versioned-literate-programming-for-tutorials
19. Literate Programming in the Large
Timothy Daly
Axiom is an open source computer algebra system written mostly in Common Lisp. As one of the original authors at IBM Research I wrote a fair amount of code. Later Axiom was sold commercially as a competitor to Mathematica and Maple. When it was later withdrawn from the market I was given the code. It was soon apparent that, while what the code did was clear, why it did what it did was not. Being unable to understand my own code was a shock. Eventually I decided to reshape the code base using Knuth’s Literate Programming technology. The idea is that one should be able to read Axiom like a book directed at human understanding, a book which incidently contains the actual source code of the system. This talk is a description of the first 10 years of that effort with insights into the challenges of writing a million-line literate program.
recording release: yes license:
Video: http://videos.writethedocs.org/video/19/literate-programming-in-the-large
20. Sketchnotes: Communicate Complex Ideas Quickly
Jennifer Hartnett-Henderson
Pick any two of the Visual, Auditory, Kinesthetic or Reading/Writing channels to communicate ideas faster and increase retention. In this 20 minute talk, I’ll show how sketchnotes help communicate complex ideas quickly. For examples, check out the Sketchnote Army blog, The Sketchnote Handbook on Flickr, and these two entries on my blog: Getting All Your Photos in One Place and Ten Years of Photos in One Hand.
Jennifer Hartnett-Henderson is a strategist, program manager and fine artist with an MFA in Digital Media. She recently returned from the Mobile Photography Awards show in NYC where she was recognized with three Honorable Mentions in two categories. Since 2000 she’s had many shows in the US and Europe and writes about photography on her blog Jennifer Hartnett Henderson. Sketchnoting helps integrate her right brain creative side with her left brain strategy work as she communicates complex ideas quickly.
We’ll cover:
What are sketchnotes? How are they different from art?
Challenge: draw one sketchnote during this talk.
What is hand lettering? How is it different from typography?
What are examples of sketchnotes in use?
Why does it work? Dual coding theory, brain research
Simple ways to get started (basic tools, easily available resources including books, videos, Flickr groups, websites)
Share your sketchnote from this talk: Twitter, Flickr #sketchnotewtd
recording release: yes license:
Video: http://videos.writethedocs.org/video/20/sketchnotes-communicate-complex-ideas-quickly
21. Search-first documentation: tags and keywords for frustrated users
Heidi Waterhouse
The days of linear documentation are over, or at least numbered. Users are much more likely to come to documentation through searches.
As writers, we need to be aware that folksonomies and search terms are the present and future, and we need to write with tags and keywords as our first step. This presentation is a quick overview of how to write technical documentation “”search-first””, with an updated understanding of indexing and keywords.
recording release: yes license:
Video: http://videos.writethedocs.org/video/21/search-first-documentation-tags-and-keywords-for
22. Lightning Talks - Tues Afteroon
Various
0:0 - Eric Holscher - ReadTheDocs.Org
4:10 - Christina Elmore - Documenting the Novel
10:24 - Mo Nishiyama - Time-Saving Communication Tips (with Empathy)
15:45 - Patrick Arlt - Designing Great Documentation (problem from 18:20 - 36, and again from 20:10 - 24 )
20:29 David on Presie ?
26:54 Mary Anthony - Funnel Cake
Melissa Lewis has requested that her lightning talk not be posted.
recording release: yes license: CC BY-SA
Video: http://videos.writethedocs.org/video/31/lightning-talks-tues-afteroon
23. UX and IA at Mozilla Support, and Helping 7.2 Million More People
James Socol
Mozilla Support has gone through a number of usability and information architecture evaluations over the past year and a half, the biggest of which helps us help 7.2 million additional people every year find the answers they need.
I’ll talk about some of the techniques and tools we’ve used (like heuristic evaluation, card sorts, treejack) and how to play along at home and apply these techniques to your own docs.
recording release: yes license:
Video: http://videos.writethedocs.org/video/22/ux-and-ia-at-mozilla-support-and-helping-72-mil
24. The technical challenges of serving docs at Google’s scale
Ashleigh Rentz
Google Code launched in 2005, hosting documentation for Google’s public APIs and Open Source software. Five years later, massive growth in the company’s developer offerings had pushed the site’s infrastructure to the max. What sorts of problems can sneak up when you go from 11 APIs to over a hundred? Or when many of those docs rapidly expand from hundreds to thousands of pages? And how can you build a serving infrastructure that won’t leave a room of execs holding their collective breath when new products launch at your annual showpiece conference?
Join Google Developer Programs’ Ashleigh Rentz for a behind-the-scenes retrospective: learn what it took to migrate a massive documentation library to a new home at Google Developers (developers.google.com) without freezing the existing site and how the new backend leverages both Open Source and Google technology to provide a CMS that truly scales.
recording release: yes license:
Video: http://videos.writethedocs.org/video/23/the-technical-challenges-of-serving-docs-at-googl
25. Helping the help pages
Ann Goliak
37signals had help pages that weren’t very helpful. That all changed with a new help section for the new Basecamp. Learn how the new help pages were developed & written and the effect they’ve had on support case load. Spoiler: it’s much lighter!
recording release: yes license:
Video: http://videos.writethedocs.org/video/24/helping-the-help-pages
26. Describe, Defend, Differentiate and Deliver
Jim R. Wilson
Many of us work for companies that fancy themselves software companies. Nominally though, what we produce is functionality, not software. And functionality is only worth while if people can use it.
In this talk, I’ll advocate for a wholistic approach to software development which incorporates documentation thinking at many levels. Documentation in its many forms can achieve diverse and sometimes accidental goals. With battle scars from real situations, I’ll show how you can use documentation not only to describe, but to defend, differentiate and deliver.
recording release: yes license:
Video: http://videos.writethedocs.org/video/25/describe-defend-differentiate-and-deliver
27. Play and Pragmatism: Recapturing the Beginner’s Mind
Jonathan Mukai-Heidt
Canceled!!!
recording release: yes license:
Video: http://videos.writethedocs.org/video/26/play-and-pragmatism-recapturing-the-beginners-m
28. Lightning Talks - never?
Various
Melissa Lewis has requested that her lightning talk not be posted.
recording release: maybe
Video: http://videos.writethedocs.org/video/32/lightning-talks-never
29. Docs as Marketing: Make Your API Irresistible
Adam DuVander
Docs share knowledge, docs teach concepts, but docs done right can also bring in new customers. While developers might not like to admit it, documentation is now a form of marketing. Companies are building businesses on APIs, so how the technical details are communicated becomes as important as a product feature matrix. To succeed in this new reality, approach documentation with the same attention to detail and polish as other marketing. This talk shares lessons learned from observing the good and bad from hundreds of API providers and shares the ways the best are making their APIs irresistible.
recording release: yes license:
Video: http://videos.writethedocs.org/video/27/docs-as-marketing-make-your-api-irresistible
30. Build a Bakery: Making cake, eating it and planning for future cake too
Lauren Rother, Fred Lifton
Most of our work as technical writers is geared toward persons external to the company (users, customers, consumers, etc.), so our first concern is creating something engaging and useful for them. Some of our tasks and projects, however, require us to consider a more complex audience.
At Puppet Labs, the documentation team curates, evaluates and edits internal documents (both inter-team and intra-team) and develops documentation meant to be used by internal employees, with the knowledge that these documents may one day need to become external documents. The team also develops documentation guidelines that are meant to be followed by internal employees and external users.
Lauren Rother and Fred Lifton of Puppet Labs will discuss the way in which these tasks complicate the usual notion of audience, and the way in which they approach and manage working on projects that require an eye on the future as well as the present.
recording release: yes license:
Video: http://videos.writethedocs.org/video/28/build-a-bakery-making-cake-eating-it-and-planni
31. Integrating Development, Documentation and Reporting
Ana Nelson
Let’s explore the amazing things that happen when you combine reporting with documentation. We’ll start with a retro-chic command-line task management tool named ‘ado’, and create a beautifully modern D3-based interactive task explorer (no server necessary). Learn how powerful documentation-driven development can be, and the benefits of freeing documentation and reporting from their usual separate silos.
In this talk we will simultaneously document Bash, Python, SQL, CSS, HTML and JavaScript using HTML, PDF, epub, Excel and .docx formats (with just a single command!). You’ll learn about Dexy, the document and data automation tool that makes this possible by working alongside the documentation tools you already know and love.
recording release: yes license:
Video: http://videos.writethedocs.org/video/29/integrating-development-documentation-and-report
32. Lightning Talks Tues Evening
0:0 Keri Meredith - Customer Learning is Continuous
6:55 Luke Frankel - Search the Docs
12:04 wraithan (Chris McDonald) - Read the Docs needs better Docs
Nóirín Plunkett - Collaborate
Melissa Lewis has requested that her lightning talk not be posted.
recording release: yes license:
Video: http://videos.writethedocs.org/video/30/lightning-talks-tues-evening
Location
--------
Room 1
About the group
---------------
Write the Docs is a two-day conference focused on documentation systems, tech writing theory, and information delivery.