WTD2015.md

Summary of Write the Docs:

A smattering of good stuff from the conf:

Day 1:

1. You won't know what you need to fix (in the docs) until you validate what you've written by having someone else read it
2. It takes a lot to break through to understanding (ex. Helen Kellar) but what we do to make sure we're communicating properly matters.
3. When testers and tech writers work together, you get a better end product because the tester is the voice of the customer when the customer isn't around.
4. Look back at past tickets--were they answered using a reference to a doc? could it be answered with a reference to an existing doc? add a link to the doc or create a doc for it if there isn't one.
5. Tutorials are great for basic understanding, but use-case based walkthroughs are better once basic knowledge is acheived
6. A walk-though is similar to a tutorial but goes deeper: it knows who it's talking to and what they want to do
7. A walk-through assumes a certain basic knowledge, provides tips along the way, and shows customer how to accomplish a complex task and help train them to accomplish similar tasks in future with minimal confusion
8. Scenario based documentation can guide users / readers to accomplish their goals -- analogy with dungeons and dragons
9. Know your customers--know what they are trying to solve and what road blocks they're hitting.
10. Develop customer profiles to better understant their needs
11. Scenario based docs are not tutorials and not marketing case studies--rather they go beyond the tutorial to deliver what marketing folks promised
12. Use video strategically as a supplement; keep them short and only as an augmentation.
13. Have fun with it
14. Article: How people read on the web http://www.nngroup.com/articles/how-users-read-on-the-web/
15. Keep in mind how ppl read on the web--they focus on meaningful text and images, the beginnings of paragraphs, and the left hand side
16. Use bullet lists, variations in typeface (bold, italics, color), code snippets with shorter text and well structured short paragraphs
17. Search: Different users will word the same question differently so have many roads to access docs to match answers to their searches
18. Remember that no one reads text above or below code snippets--they just copy and paste so make it a no-brainer
19. When users run into errors they often google the error and get stackoverflow, not your docs
20. Go on stackoverflow and clean up answers if you can.
21. Users are hiring your docs to control for most failures, make error messages explain how to fix the problem
22. Good docs don't happen over night
23. Use GitHub to manage docs
24. Don't write a reference guide--those are only good if you already know something
25. Helping users remember what they read using by identigying goals, focusing attention, encoding strong memories, engaging you audience, and Sparking Attention
26. Itentify goals, what to I want them to remember? What do I want them to do?
27. Focus the attention of your reader: people forget b/c they can't pay attention to everything so highlight the best stuff
28. Encode stronger memories: use a narrative, an analogy, or an image to help remember (ex. Dropbox docs)
29. Engage your audience so you know them better and use that knowledge to make them feel welcome in your docs--like they are at home or talking with an old friend.
30. Spark action with emotion: emotion helps us remember. Headlines, awe, anger, anxiety are shared the most, so give emotional cookies to help your users love you. Have a clear call to action

Day 2:

1. Ward Cunningham has an amazing brain. (He is the creator of the wiki)
2. Federated Wiki: you can play with it if you go to http://write.asia.wiki.org/ <--this is really really cool to mess around with!!!
3. "Just as the first wiki changed how people write, our new wiki will change how people work"
4. "I want to be able to DO work in a wiki"
5. The documentation becomes a spin-off of leaving your work behind
6. Federated wiki is a place where you make stuff that lasts, and collaborate and share with others, but also borrow from others
7. Refactoring vs. editing; federation vs. plagiarism.
8. the idea is to licence stuff for others to use any way they would like, then you can use what others have created and build on it together
9. Your domain is your identity, every page has a welcome visitors; use markdown to create links
10. The federated wiki is a new way to browse and create content on the web.
11. Every page has a history--the redo/undo stack of what where who and when the doc was updated/edited/copied
12. Streamline the path for those interested in helping with docs--make it easy for them to contribute
13. Create invitations, not roadblocks--example MDN the edit button changed to darker blue and got 30% more clicks
14. Expose what areas need help and communicate in what ways ppl can help
15. At MDN one roadblock was that people don't realize each page is an editable wiki
16. Enable engineers to find, create, and maintain docs by learning their workflow and integrating docs into it--adapt the engineer's workflow into hte platform
17. Momentum matters--if making change in doc procedures, start small, iterate often
18. Authority and influence don't derive from your resume, but from action and impact.
19. Creativity can help create engaging docs and make writing docs more fun.
20. Use soft skills to help build relationships in house to accomplish what needs doing.
21. Express patience and encouragement with contributers
22. Write simply; simply write.
23. Review using pull requests--but comments are the most important part of pull requests to have a trackable discussion about the changes.
24. Using pull requests to track changes helps keep a record of everything that's changed about a doc
25. Good for new people coming in so they can see the doc's history
26. Everyone can hack on the docs if they're on GitHub
27. Use GitHub for docs
28. Publishing is simple--> you merge, it deploys
29. Measure everything about the docs: page views, clicks, time on the page, load time, tickets associated with etc.
30. Graph all of it
31. Use mentoring to help teach ppl to write good docs
32. When working with tickets try to discover which docs would help; write them if none exist, improve if they are poor
33. Beginning employees have new eyes, let them contribute and choose what to write, as they gain confidence will seek out ways to contribute

Link to videos of the talks:

https://www.youtube.com/user/NextDayVideo/videos

Links to talks from 2014 and 2013 Write the Docs

http://videos.writethedocs.org/category

My favorite talk that I recommend everyone doing support should watch:

Support Driven Development http://videos.writethedocs.org/video/8/getting-developers-and-engineers-to-write-the-doc