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.

1. Taking Documentation to the Next Level
in Young Software Projects
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

2. Do you contribute to documentation?



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?
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

3. Structure of this talk
Problems of documentation in young software
projects

Some research into the use of mailing lists and
discussion forums



Comments about online Erlang documentation
Suggestions for developing more and better
documentation
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

4. Documentation and the adoption curve
Innovators Early Adopters
Mainstream success
Documentation
needed
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media
Publishers (best case)
Decline
Publishers (worst case)

5. Documentation by the innovators
Software developers tend to write for other
people like themselves

Assume deep background knowledge that can
be transferred to their project

Elements of innovator documentation

Architectural justifications

Comparisons to other projects

Quick-starts

Reference material

Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

6. Example: Riak documentation

Focuses on architecture

Useful to distinguish Riak from similar projects

But does not connect architecture to use cases
to make the information practical
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

7. Early adopters arrive



They possess enough background to use
innovators' documentation
Consider documentation adequate
Promote project and generate enthusiasm that
draws other users
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

8. Mainstream users arrive



Confused and alienated by the documentation
Desperately search for help, which may or may
not arrive
Leave project if not engaged and aided
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

9. Research on mailing lists

Used on every project

Easy to quantify results

Every question reflects a failure at documentation
Perhaps the feature is undocumented

Perhaps the documentation could not be found

Perhaps the documentation didn't seem
relevant to the question

Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

10. Questions asked about mailing lists

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
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

11. How many questions were answered?
Unanswered
7
7
7
5
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media
Answered
Fedora Linux
7
Ubuntu Linux
7
Rails
7
Perl
9

12. So, are mailing lists effective?
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

13. How is Erlang documentation?
Erlang is in a lucky position

It is not a young project

It has been able to develop innumerable
training materials over the decades

Several publishers have released
professional books

Functional principles have spread
throughout the programming field

One must consider the whole information
ecosystem

Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

14. Comments on erlang.org

Site is run by Ericsson

Potentially backed by lots of resources

But how much attention does the company
give it?
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

15. Comments on erlang.org

Getting Started
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

16. Assumptions in documentation

Reader understands the math

Reader understands the notion of recursion

Reader has seen factorials used as an example
of recursive programming
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

17. Focusing on the code

Reader must be able to pick out “active ingredients”
in code
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

18. Focusing on the executable code

Reader must determine when and why each
function runs
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

19. Comments on erlang.org

An Erlang Course
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

20. Questions left by course


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.

Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

21. Comments on erlangcentral.org

Site run by the Industrial Erlang User Group

Points to wide range of documents and other sites

Solicits user contributions to wiki
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

22. Criteria for evaluating documentation

Availability—does it exist at all?

Findability—can readers get answers?

Quality—accuracy, readability, relevance, etc.
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

23. Availability—try crowdsourcing




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”
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

24. Crowdsourcing has a history
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

25. Models for crowdsourcing

Development and study of Talmud

Greek symposium
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

26. Mobilizing users for documentation

Search for bloggers, contributors to forums

External motivations can encourage contributions

Access to developers is a motivation

Don't strive for unity—embrace multivocality

Let people use their own favorite media
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

27. Availability—FLOSS Manuals
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

28. Availability—FLOSS Manuals

Coordinate volunteers around the world

Create conventional books

Foster translations
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

29. FLOSS Manuals—sprints

Bring volunteers together in one space

Usually sponsored by an open source project

Google has hosted many documentation sprints
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

30. Findability—more than a search engine

Add boxes for people to recommend documents

“Read before this document”

“Read after this document”

Long-term goal: spider creates recommended
paths through documents
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

31. Quality—What's the ultimate goal?

After reading the document, can the reader
accomplish the task she set out to do?
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

32. Quality—A/B testing



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
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

33. Summary



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
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media

34. About me
@praxagora
andyo@oreilly.com
http://programming.oreilly.com/andyo
Erlang Factory, 23 October 2013
Andy Oram, O'Reilly Media