Upload
andy-oram
View
478
Download
1
Tags:
Embed Size (px)
DESCRIPTION
To spread beyond the early adopters and reach a mainstream audience, a software project requires good documentation and training materials. This presentation looks at some research into documentation, examines some examples, and proposes solutions.
Citation preview
Taking Documentation to the Next Level
in Young Software Projects
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media
Do you contribute to documentation?
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Have you created a web page, blog posting, webinar, video, etc. about a software project?
Have you answered a question on a mailing list or forum?
Have you asked a question on a mailing list or forum?
Structure of this talk
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Problems of documentation in young software projects
Some research into the use of mailing lists and discussion forums
Suggestions for developing more and better documentation
Comments about online Erlang documentation
Documentation and the adoption curve
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Innovators
Early AdoptersMainstream success
Decline
Publishers (best case)
Publishers (worst case)
Documentationneeded
Documentation by the innovators
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Software developers tend to write for other people like themselves
Assume deep background knowledge that can be transferred to their projectElements of innovator documentationArchitectural justifications
Comparisons to other projectsQuick-startsReference material
Example: Riak documentation
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Focuses on architecture
Useful to distinguish Riak from similar projects
But does not connect architecture to use cases to make the information practical
Early adopters arrive
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
They possess enough background to use innovators' documentation
Consider documentation adequate
Promote project and generate enthusiasm that draws other users
Mainstream users arrive
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Confused and alienated by the documentation
Desperately search for help, which may or may not arrive
Leave project if not engaged and aided
Research on mailing lists
Used on every projectEasy to quantify resultsEvery question reflects a failure at documentationPerhaps the feature is
undocumentedPerhaps the documentation could not be foundPerhaps the documentation didn't seem relevant to the question
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Questions asked about mailing lists
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
How many technical questions get answered?
How long does it take to get an answer?
How much noise is on the thread?
http://praxagora.com/andyo/professional/mailing_list/mailing_list.html http://www.praxagora.com/andyo/professional/mailing_list_follow_up
How many questions were answered?
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
7 7Fedora Linux
7 7Ubuntu Linux
5 9Perl
7 7Rails
AnsweredUnanswered
So, are mailing lists effective?
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
How is Erlang documentation?
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Erlang is in a lucky positionIt is not a young projectIt has been able to develop innumerable training materials over the decadesSeveral publishers have released professional books
One must consider the whole information ecosystem
Functional principles have spread throughout the programming field
Comments on erlang.org
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Site is run by Ericsson
Potentially backed by lots of resources
But how much attention does the company give it?
Comments on erlang.org
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Getting Started
Assumptions in documentation
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Reader understands the notion of recursion
Reader understands the math
Reader has seen factorials used as an example of recursive programming
Focusing on the code
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Reader must be able to pick out “active ingredients” in code
Focusing on the executable code
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Reader must determine when and why each function runs
Comments on erlang.org
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
An Erlang Course
Questions left by course
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Why does Erlang offer both tuples and lists?Do tuples and lists work like they do in other languages?
When do you use a tuple and when do you use a list?
Other lapses in course: unexplained syntax, isolated examples that don't build on each other, etc.
Comments on erlangcentral.org
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Site run by the Industrial Erlang User Group
Points to wide range of documents and other sites
Solicits user contributions to wiki
Criteria for evaluating documentation
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Availability—does it exist at all?
Findability—can readers get answers?
Quality—accuracy, readability, relevance, etc.
Availability—try crowdsourcing
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Your developers don't have time to write everything
Users have innate sympathy for other users
They'll generate content anyway, so you can coordinate it intelligently
Give up on “One Ring to Rule Them All”
Crowdsourcing has a history
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Models for crowdsourcing
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Development and study of Talmud
Greek symposium
Mobilizing users for documentation
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Search for bloggers, contributors to forums
Let people use their own favorite media
Don't strive for unity—embrace multivocality
Access to developers is a motivation
External motivations can encourage contributions
Availability—FLOSS Manuals
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Availability—FLOSS Manuals
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Coordinate volunteers around the world
Foster translations
Create conventional books
FLOSS Manuals—sprints
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Bring volunteers together in one space
Google has hosted many documentation sprints
Usually sponsored by an open source project
Findability—more than a search engine
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Add boxes for people to recommend documents
Long-term goal: spider creates recommended paths through documents
“Read before this document”
“Read after this document”
Quality—What's the ultimate goal?
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
After reading the document, can the reader accomplish the task she set out to do?
Quality—A/B testing
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Attach a quiz to a document
As you rewrite the document, check how well the readers can answer the quiz
Remember: a user experience encompasses more than one document
Summary
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
Documentation and training materials are crucial to mainstream adoption of young projects
A serious need exists for better documentation
Invest special efforts to create documentation, make it findable, and improve its quality
About me
Erlang Factory, 23 October 2013 Andy Oram, O'Reilly Media
@praxagora
http://programming.oreilly.com/andyo