Taking Documentation to the Next Level in Young Software Projects

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

andyo@oreilly.com

http://programming.oreilly.com/andyo