FANDOM


Open source is dominated by alpha geeks
http://xkcd.com/773/
It's hard for people following behind them to follow along -- they may not have the same background or experience

Open source -- you might find information from blog posts
Interesting posts tend to be topical

Encourage people who have written good blog posts to write a longer paper.
Sometimes it's easier to get unexperienced people to write documentation, and then use more technical people to review
Tech writers don't always come from the developers tools and language to help
other people
Get writers to write, and more technical folks can help get the formatting and tooling right
One user recommended the Python Sphinx tool to make it easier to write in .rst
Change the screenshots -- custom patches to change the screenshots depending on the language
The people doing the work should help control the tooling
Timing of meetings is always difficult due to time zones
Filing bugs for code and/or docs
Small digestable chunks
Updating or rewriting an existing manual for updates is harder than writing a new book
Top-down structure vs. bottom-up
Video documentation, and the challenges within
Using automated tools (such as Selenium) to automate the dialogs
Official docs vs. unofficial docs
Conversation and Community -- by Anne Gentle -- great book for helping team members get involved in docs: http://www.amazon.com/Conversation-Community-The-Social-Documentation/dp/0982219113 Second edition out soon with a new open source documentation chapter.
How do you recognize contributions? Attribution? Give them a leadership responsibility.
Translators make good copyeditors

Updated post-session by Anne: Thanks for recommending my book - Andy Oram wrote a great foreword to it. :) I highly recommend this McGill University study of open source documentation, "Creating and Evolving Developer Documentation: Understanding the Decisions of Open Source Contributors"

http://www.cs.mcgill.ca/~martin/papers/fse2010.pdf

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.