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 Crystal Ballroom Mon May 5, 8:15p


Eric
=========================
When: 8:15 AM Monday May 5, 2014
Where: Crystal Ballroom

None

Topics
------
1. Breakfast


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/33/breakfast 
2. Introduction
Eric Holscher

A welcome talk to the event.
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/34/introduction 
3. Flow: A Permaculture Approach to Documentation Projects
R. N. Homer Christensen

Permaculture is all the rage in the organic and urban farming circles, but it is a design science rooted in observation that has applications far beyond vegetables and fruits. 
Its basic tenets include observing the environment to discern the patterns, the risk areas, and other factors that will influence your work, and then working within those constraints using the least amount of energy and costly outside inputs to produce a harmonious, sustainable, and perennial system that yields a healthy return and requires the least amount of work to maintain.

This presentation introduces some of the core practices of permaculture that can be immediately applied to any project to make it more successful, more enjoyable, and better suited to its intended audience.

Participants will discover:

* Why it is important to design from the patterns to the details.
* The edge where two systems meet (think engineering and customer service) yields the most innovation.
* Diversity is important to incorporate and honor.
* Ways to stack function… where one element performs multiple roles (like single-sourcing).
* How to plan for zones of access… so that your audience can quickly locate the most important, most frequently used information.

It's a fresh and intuitive approach, a Zen view of something that many of us have done for years. In Permaculture, the problem is the solution. Or perhaps more properly said: in any problem lies the solution.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/35/flow-a-permaculture-approach-to-documentation-pr 
4. Communities are Awesome
Ali Spivak

The Mozilla Developer Network is an open-source documentation wiki for web developers, which is written by really passionate, smart, and inspiring people. Most are not paid employees of Mozilla. All of them are helping make the web a better place by writing, editing, and reviewing articles. How do you support a diverse community, acknowledge many different voices and perspectives, be open and inclusive, and still get things done (especially when you can't force anyone to do anything)?  In this session, I’ll share what I’ve learned (and keep learning) by working with, in, and for volunteer communities; including how to be more transparent, create opportunity, and broadly share ownership. 

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/36/communities-are-awesome 
5. The New Sheriff in Town: Bringing Documentation Out of Chaos
Heidi Waterhouse

It is rarely that a documentarian is brought in at the beginning of a
 company or project. More commonly, we are called in sometime just 
before or sometimes slightly after a project is released. We need to hit
 the ground running, maximize our value, and deliver something before 
the product is rejected for being undocumented.
Join me for a discussion of my techniques and stress-tested questions
 for how to get minimum viable documentation out of a motley collection 
of gists, outdated specs, and time-crunched developers. See some 
immediately-applicable techniques for getting good-enough documentation 
out the door.
My specialty as a technical writer is establishing a minimum viable 
documentation set, establishing tools and procedures, and training in a 
less battle-hardened writer to take over.
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/37/new_sheriff_town_bringing_documentation_out_chaos 
6. Break


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/38/break 
7. Ignorance is Strength: Writing Documentation by Learning as You Go
Amalia Hawkins

When your company’s codebase is large, complicated, and mostly undocumented, there is a huge burden to bring new hires up to speed — not to mention facilitate communication between distributed teams. How can you leverage the knowledge of experienced engineers — and the ignorance of new engineers — to guide your efforts and create a valuable resource?

At MongoDB, we now have the Hitchhiker’s Guide to the Codebase, an internal documentation resource covering everything from an introduction to our build tool to detailed explanations of internal server mechanisms. Content is contributed by engineers across the company, based on their frustrations and requests from other engineers, and edited by volunteers. The most valuable content is often written by engineers who had to struggle through learning about those topics on their own.

I’ll talk about how I started this initiative without any knowledge or power, how I recruited volunteers, and the impact this has had on productivity at our company. 
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/39/ignorance-is-strength-writing-documentation-by-l 
8. Did It In Minutes: The Art of Documenting Meeting Notes
Mo Nishiyama

If elegant technical help pages are the shiny, sleek roadsters of the documentation world, the plebeian meeting minutes are the dump trucks. Despite being regarded as an unglamorous business tool, minutes serve an important function for communicating effectively with colleagues.

Meeting minutes document changes to business operations, chronicle the decisions that were made, capture the essential gist of discussions, and serve as handy references for those colleagues who were unable to attend the meeting--or for those who indulged in siestas during the gathering. Minutes can even justify whether a meeting was necessary in the first place.

Effective minutes can save companies labor costs: well-written meeting notes can prevent both meeting organizers and absent team members valuable time that would otherwise be spent trying to bring absentees up to speed. Accurate meeting notes can clearly define policies and expectations in a workgroup.

In this presentation, we will discuss best practices for documenting and curating meeting notes. Using meeting templates, de-mystifying technical jargons, breaking free of the chronological reporting, adhering to the WTF (Write The Facts) approach, carving time for editing notes, charting follow-up tasks, and judiciously spicing up otherwise-mundane topics are  examples of these best practices. Special emphasis will be placed on writing with clarity and empathy in mind for team members, whether they were present at the meeting or not.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/40/did-it-in-minutes-the-art-of-documenting-meeting 
9. Hacking the English Language
Nina Vyedin

A good doc is like a good program: beautifully architected, free of clutter, and easy for others to understand and maintain. In this session we’ll explore a programmatic approach to writing conceptual content, including the application of design patterns to writing, principles of good doc structure (architecture), and the importance of word choice and clarity (naming your variables). 

We’ll review “code samples”  - examples of real sentences from docs - and refactor them into clear, straightforward explanations that help the reader learn. Throughout the talk, we’ll introduce a new way for developers to think about writing and for writers to think about the technology we are documenting.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/41/hacking-the-english-language 
10. Lunch


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/42/lunch 
11. Monday Lightning Talks


(00:00) Marcia Riefer Johnston - @MarciaRJohnston - Write Tight(er)—Revisited

(0:05:28) Dirk Myers @DirkMyers Test Those Docs!

(0:10:49) Eric takes a picture

(0:11:04) Anne Gentle @AnneGentle Open Source Docs the Hard Way

(0:17:22) Dan Stevens Write, Measure, Repeat

(0:21:14) Chuck Toporek @ChuckDude EPUB in a Nutshell 
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/43/monday-lightning-talks 
12. Documenting Domain Specific Knowledge
Alex Gaynor

Most of my career as a software engineer, I've written documentation for very general purpose tools, where users' had an existing familiarity. For the last six months I've been working on a cryptography library, a domain most developers are ignorant of. We set out with the goal of making our documentation accessible to any developer, regardless of previous cryptographic experience, which presents unique challenges. This talk will dive into what these challenges are, and how we try to solve them.
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/44/documenting-domain-specific-knowledge 
13. Graphical Explanations
Geoffrey Grosenbach

As Frederick Brooks observed in "The Mythical Man-Month", computer programmers build not with boards and hammers but with "pure thought stuff". Sometimes it can be difficult to explain abstract technical concepts just with words. Fortunately we can use colors, shapes and animations to explain ideas that would otherwise be confusing. You'll see dozens of examples and learn to make your own.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/45/graphical-explanations 
14. Minimum Viable Documentation
Matthew Lyon

You're working at a startup building a "minimum viable product" -- and everything about the product is being cut down to bare minimum to reduce the risk and cost of failure.  Deciding what to include in "Minimum Viable" is difficult, and the value of documentation in service of product development is often misunderstood by project managers who work in this style, who often choose to forego documentation altogether.  

I will make the case for including documentation in "viable": We'll consider ways of understanding your target audience, helping introduce them to your software and getting them unstuck, and make the case for minimum-viable in-house developer documentation.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/46/minimum-viable-documentation 
15. What Makes Good API Documentation: An Example-Based Approach
Lois Patterson

We'll take a tour through API documentation land, comparing the features and usability of different API doc sets. Interoperability is important, and making an easy-to-use API available can be a significant component of a company's success. Based on my own research, plus consultation with software engineers, product managers, and other technical writers, I will discuss what makes excellent API documentation. Here are some samples of great API documentation features that I have found.
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/47/what-makes-good-api-documentation-an-example-bas 
16. Documentation at Scale
Kenneth Reitz

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

Documentation doesn't always have to be about a software workflow or open source project — it can be used to develop and convey ideas much larger than yourself. Information architecture is a powerful tool for developing ideas over time. It enables us to evolve and distill information at a much larger scale than a single person or team could ever achieve on their own. 

Take these concepts, and apply open source workflow tools like GitHub's Pull Requests and Write the Docs, and the distributed evolution of ideas and information has never been more accessible.

We'll explore these concepts, learn how to foster a community of distributed contributors, encourage contributions early on, and more.

Python-Guide.org will be used as an example, a Python-specific knowledge base written by 168 people and accessed by over 50,000 people every month. 

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/48/documentation-at-scale 
17. Break


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/49/break-0 
18. TechDocs at Twitter: Creating the Culture of Documentation
Simeon Franklin, Marko Gargenta

Twitter Engineering has grown quickly, to well over a thousand engineers in the space of a few years. In the process, scores of teams have developed hundreds of individual services and libraries. During this time, these teams have been supported by at most three full­time tech writers.

This is a story of how we work towards creating the culture of documentation. To implement this culture, we needed to introduce new tools that are seamless for the developer workflow and to bring the teams along with education and training. In this talk, you will learn what worked and what didn’t for Twitter engineering documentation.

Twitter is a large organization with many projects, a variety of languages, and wildly varying standards for documentation. This talk shares the experiences of our newly formed university engineering education division. 

* Building and distributing documentation tools for a large in-house technical audience
* Evangelizing for broader developer participation in documentation
* Using rewards, policies, metrics, and public shame to drive documentation quality
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/50/techdocs-at-twitter-creating-the-culture-of-docu 
19. Say More With Less: Writing for a Global Audience
Maxwell Hoffmann

"We
 don't do translation; we only post to our website in English." Think 
again. Over 80% of Internet users have English as a second language or 
as "no language." Whatever you share online is destined to be translated
 into other languages with Google Translate and other free tools.



You
 don't have to buy an expensive set of localization/translation tools to
 get started. You don't even have to create translation memory. You 
simply have to think and write differently. And, most of what your high 
school English teacher taught you won't be of any help. This brief 
presentation will cover the key stumbling blocks that Maxwell Hoffmann 
discovered during his 12 years in the translation industry. In this 
session you will get a taste of how to "write tight", eliminate 
stair-step lists, minimize unnecessary tables and the trouble with 
gerunds, among other things. The good news? This method of content 
creation is also more effective for client retention with your clientele
 who are native English speakers.
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/51/writing-for-your-other-half 
20. Data, Documentation and Memory
Amelia Abreu

In this presentation, I explore the role of documentation and technical writing in shaping larger recordkeeping and memory practices. How does documentation shape institutional memory? How does it validate and enforce definitions and boundaries? What roles do documentarians play in the larger ecosystem of development?

Drawing on my experiences as a UX Researcher and an academic HCI background, I introduce concepts from archival and critical theory. Examining both data and metadata structures, I argue for an infrastructural understanding of documentation, one that acknowledges documentation practice as crucial scaffolding for the development process. In conclusion, I present recommendations for maximizing the value of archival documentation and improving data retention and retrieval.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/52/data-documentation-and-memory 
21. Death by Documentation
Christina Elmore

The urge to document is at the root of many bad presentation habits.

Despite a renaissance in the
 art of presentation - think TED Talks, Nancy Duarte, Prezi, and Ignite –
 we still experience more bad presentations than any lifetime deserves. 
Even with compelling content and conquered nerves, a presenter’s visual 
materials can totally tank a talk. And documentation is often to blame. 

The real culprit is a conflation of documentation and presentation. Many slide collections end up being an awkward mash-up of the two, and documents suffer when we force them into the mental model of a presentation. (NASA and the military offer striking examples of these failures.) Why have the
 differences between documentation and presentation been lost? How can 
we make better sense of these two forms to create more engaging 
presentations and better documents?
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/53/death-by-documentation 
22. End


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/55/end 
23. Party Reminder


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/54/party-reminder 
24. Venue Open


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/56/venue-open 
25. Breakfast


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/57/breakfast-0 
26. Announcements


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/58/announcements 
27. Putting the (Docs) Cart Before the (Standards) Horse
Drew Jaynes

When people think of documentation standards, I'd wager the first thing that comes to mind is probably something like "uniformity", or "best practice", or "one voice". And in consideration of that, most people probably also view standards as the de facto "starting place" for all the things to come after.

So what happens when you turn that idea on its head, that is to say, 'write the documentation first, and develop standards later'?

In the WordPress open source project, we did that. We developed an inline documentation standard using 10 years of contributions as a starting place.

This talk will cover some of the challenges we overcame to develop a new standard using legacy documentation.
Also:  

* Tools we used to assess our existing documentation "style".
* How our new standards have been applied in practice.
* How having a standard has allowed the docs team to rise to equal footing.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/59/putting-the-docs-cart-before-the-standards-horse 
28. From Docs to Engineering and Back Again
Susan Salituro

When you head into a career as an API technical writer, you’re treading dangerously close to engineering territory. You have to know enough about software development to write for an audience of software engineers, yet you also have to be an experienced and efficient writer of English prose. When a writer crosses the line into software development, how does she balance the need to write with the need to code (short of criticizing the grammar in code comments)?

This is the story of how I began migrating between the documentation and software engineering worlds, how the combination of the two can form a valid career, and some of the insights I gained about both roles in the process. 

 recording release: no  
 Video: http://videos.writethedocs.org/video/60/from-docs-to-engineering-and-back-again 
29. Don't Write Documentation
James Pearson

We can all agree the world is under-documented.  However, some of the documentation that currently exists, shouldn't, and it trains users to ignore the other docs we've spent so much time crafting.

We'll talk about common documentation traps, including autogenerated text and poka-yoke replacements, and how to recognize and purge them in your own projects to create a better user experience.
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/61/dont-write-documentation 
30. Make Music Not Noise
Christopher Kelleher

Can the values of music guide us to create better documentation? We’ll look at examples of noisy documentation and consider how we can use the noise vs. music distinction to improve the world by documenting it better.

sound without structure = noise
sound + satisfying structure = music
information + satisfying structure = successful documentation

First we’ll examine cases of intentional noise – documents that are designed to be hard to follow. Think convoluted cable bills or droning usage agreements. This is noise with a purpose: if we give up on following along, the document has done its job because the original goal was to make us surrender, not understand. We’ll talk about how to isolate the noise and demand higher standards.

And then there are documents that mean well but perform badly — the audience can discern a melody, but it’s either buried or gratingly inconsistent. Examples include tediously detailed consent forms, haphazard project documents, or reports that drift through random facts and jargon. This is the dissonance of badly structured information — making sound without making sense. Applying a musicality standard can guide authors out of the muck.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/62/make-music-not-noise 
31. Break


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/63/break-1 
32. Instrumentation as Living Documentation: Teaching Humans About Complex Systems
Brian L. Troutwine

Human intuition about complex systems is pretty abysmal: we have neither the scope of imagination or the experiences necessary to predict the varied behaviors of our creations. Humans operating these systems--in stable and disaster situations--must rely on a combination of faulty intuition, information coming out of the system and static documentation created by the designers of the system to guide them in their actions. In this talk I will focus on the interaction of instrumentation and static documentation on human operators. In particular, I will contend that by insisting on rich instrumentation system designers will gain a deeper intuition of their work, generating better static documentation and more contextual information for use by operators. I will further contend that this environment is conducive to smooth functioning of the system and creates a culture of constant improvement among the operators and the engineers. 

I will use historical examples and my professional experience to argue this position. 

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/64/instrumentation-as-living-documentation-teaching 
33. We Strongly Recommend You Write Best Practices
Lauren Rother

Writing best practices documentation is definitely an art, but that doesn't mean a little science can't help us along. Through some trial and error, I've uncovered some tenets of writing engaging, readable best practices docs. I'll walk through a bit of my path to discovery as I highlight and give examples of successful and (enthusiastic) reader-approved best practices documents. 


 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/65/we-strongly-recommend-you-write-best-practices 
34. Wabi-Sabi Writing
Scot Marvin

Agile development environments bring increased versions, more due dates, and the accompanying headaches that go with publishing more frequently. And yet, writers must still maintain an emphasis on helping readers with the best documentation we can produce. So, how do we focus on producing documentation that is perfect, permanent, and complete? 

We don't.

The Japanese concept of wabi-sabi refers to an appreciation of the beauty in the imperfect, impermanent, and incomplete. These are qualities of Agile documentation. And they're beautiful. No, really. They are. This talk will detail my journey to let go (meh, for the most part) of the need for technical communication perfection. I will also offer tips for my fellow control freaks.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/66/wabi-sabi-writing 
35. Strategies to Fight Documentation Inertia
Britta Gustafson

I'm a non-developer working with a community including a bunch of mostly-volunteer developers, and for years our developer documentation wiki was quiet and mostly static. I didn't touch it, since I don't know enough to work on developer resources, right? Wait, no! I realized that even if I can't update it all myself, I can help the developers with it, including a bit of persuading them.

I'll explain some of my strategies for making working on documentation more appealing and rewarding for developers, including by lending it some aspects of the quick feedback that people get when writing code.

This includes things like: Ways to make the wiki feel active and alive, since nobody likes to hang out in a ghost town. Good questions to ask that encourage people to write things down. How to make first edits easy with bite-sized tasks and prominent "todos" that entice people to click that edit button. Finding people who prefer to ask permission first before making changes, and being there to give them permission! And the best "trick": advice for effective ways to thank people a lot, publicly and specifically.
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/67/strategies-to-fight-documentation-inertia 
36. Lunch


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/68/lunch-0 
37. Tuesday Lightning Talks


(00:00)
(0:00:12)
(0:04:43)
(0:10:26)
(0:13:48)
(0:14:44)
(0:19:09)
(0:19:35)
(0:25:05)
(0:30:23)
(0:31:10)
Maxwell Hoffmann
@maxwellhoffmann
Ink Is in PDX’s DNA

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/69/tuesday-lightning-talks 
38. Scale for Support Without Losing Personality
L.S. Cook

It is rarely that a documentarian is brought in at the beginning of a company or project. More commonly, we are called in sometime just before or sometimes slightly after a project is released. We need to hit the ground running, maximize our value, and deliver something before the product is rejected for being undocumented.

Join me for a discussion of my techniques and stress-tested questions for how to get minimum viable documentation out of a motley collection of gists, outdated specs, and time-crunched developers. See some immediately-applicable techniques for getting good-enough documentation out the door.

My specialty as a technical writer is establishing a minimum viable documentation set, establishing tools and procedures, and training in a less battle-hardened writer to take over. 
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/70/the-new-sheriff-in-town-bringing-documentation-o 
39. The Getting Stopped Experience: Improving Your Content’s First Impression
Jared Bhatti

The “Getting Started” page of your product is the most important page for bringing new people onto your product. In the best case, it introduces readers to your product and convinces them to use it. Too often, though, it becomes the “Getting Stopped” experience, with readers getting repeatedly frustrated. Poor documentation, from the Getting Started page on, causes many developers to leave your content and product behind.  Outdated information, rude warnings, bad metrics, and poor content strategy all contribute to the “Getting Stopped” experience. 

This talk examines several practical solutions that tech writers can use to engage readers and create a better first impression.  Drawing on examples from Google’s Cloud developer documentation, I focus on how users can define solid metrics for success and encourage reader participation.  With these simple but robust solutions, you too can bring more people to your product, getting them started and keeping them around. 

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/71/the-getting-stopped-experience-improving-your-co 
40. More Than a Reference: Better APIs Through Empathy
Zach Corleissen

You've probably seen (and maybe even written) API documentation so reference-complete, it puts the OED to shame. Useful API docs cover every endpoint, parameter and variable--but not all API methods deserve equal prominence.  

This talk is about creating better API documentation through empathy. We'll talk about delighting readers by knowing your audience, showing them where to begin, and explaining why your API matters in the first place.

 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/72/more-than-a-reference-better-apis-through-empath 
41. Break


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/73/break-2 
42. Ditch Your CMS With Git and Static Site Generators
Patrick Arlt

The command line can be your best friend! Git is an amazing tool that helps developers collaborate, review and manage code, but these same tool also work for writing and managing documentation.

Learn how we use tools like Git, Middleman and Markdown in building and managing the ArcGIS for Developers website (https://developers.arcgis.com). I'll share some Git basics and give some insight into how we do things like create, collaborate and version our documentation all the way up to how the final website is built and deployed.
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/74/ditch-your-cms-with-git-and-static-site-generator 
43. Documentation as a Product
Mark Tattersall

"Write the Docs" is so often a line item found at the end of a project plan. But documentation deserves so much more attention and thought as good documentation does more than just describe how to use or implement a new feature, particularly in the case of API documentation. It is both the shop window and instruction manual. The tone of the documentation represents your product, and the complexity, simplicity or ‘magic' needs to shine through.

My talk will focus on two objectives:

1) Why does Documentation deserve product planning on its own?

2) What do you mean Documentation as a Product?
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/75/documentation-as-a-product 
44. Closing Remarks
Eric Holscher

(Needs description.) 
 recording release: yes license:   
 Video: http://videos.writethedocs.org/video/76/closing-remarks 
45. End


(Needs description.) 
 recording release: no  
 Video: http://videos.writethedocs.org/video/77/end-0 


Location
--------
Crystal Ballroom


About the group
---------------
Write the Docs is a two-day conference focused on documentation systems, tech writing theory, and information delivery.