The Four Letters Word of FLOSS: DOCS

Bastien Guerry

October 2011

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 1 / 34

Outline1 Good documentation?2 Three problems about FLOSS documentation3 Factors worsening these problems4 The Beauty and the Beast5 The ego-rewarding scale: code and docs6 How to make DOCS available?7 How to make DOCS usable?8 How to make DOCS discoverable?9 Summary 1: focus on Your Single Simple Tutorial10 Writing docs the simple and collaborative way11 Emacs: the "self-documenting" editor12 Summary 2: both newbies and power-users are key13 Thanks!

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 2 / 34

Good documentation? Inspiring quotes.

"Love doesn’t need docs as much as docs needs love."-- B. Franklin

"When you make up a quote, just use my signature."-- B. Franklin

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 3 / 34

Good documentation? Stepping back a bit.

"Moving forward about documentation requires you tothink a bit backward."

-- Anonymous

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 4 / 34

Three problems about FLOSS documentation

1 Availability: Those who can write documentation don’t write it.2 Usability: Those who find documentation cannot use it – for

whatever reasons: format, language, etc.3 Discoverability: Those who need documentation don’t find it

easily.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 5 / 34

Prioritizing these three problems

1 Try to write documentation2 Try to make it useful for many users3 Try to make it easily discoverable

This, of course, is a virtuous circle: if developers or power-userswrite documentation, newbies will pressure them to make it moreadapted; and the more users pressuring documentation writers, themore easily users will find the docs.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 6 / 34

Worsening factor #1: Feature-unstable application

Hypothesis: Applications with a stable set of features are easier todocument.

Documentation addresses the software’s features: the more unstablethe features, the more work for documentation writers andmaintainers.

Lemma: Applications with few upstream/downstream dependenciesare easier to document.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 7 / 34

Worsening factor #2: A big users/developers gap

Hypothesis: Good documentation requires good communicationchannels between users and developers.

Note that this is probably independant from the users/developersratio: you can have a large users/developers ratio and still maintain adensily connected community of people writing documentation (theshape and the size of a community are not deterministically tiedtogether.)

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 8 / 34

Worsening factor #3: Non-specific applications

Hypothesis: Specific applications are easier to document thannon-specific applications.

Very specific ("unix-like") tools have simple documentation (usuallyman pages) because it’s fairly easy to cover all possible usages. Withnon-specific applications, it’s impossible.

E.g. Sugar activities makes sense in many educational contexts: whatpeople expect as "manuals" can go from basic software usage to realeducational-oriented case-studies.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 9 / 34

Let’s focus on the right things!

1 First document stable features2 Then encourage good communication between users and

developers3 And focus on specific documentation with a clear

purpose/audience

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 10 / 34

The Beauty and the Beast

The beauty A community of users/developers (probably with a highpower-users/developers ratio) efficiently communicatingwith each others, writing plain text docs (from tutorialsto full-fledged manuals) collaboratively for a specific andstandalone tool with a stable set of features, these docsbeing directly accessible through the software itself.

The beast A rich application with a large set of unstable features,with a big users/developers gap and very fewpower-users; documentation is written in variousnon-ascii formats and scattered through the web (surelynot accessible from the software itself) and there areonly few opportunities to collaborate on writing it.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 11 / 34

The ego-rewarding scale: code and docs

Task Code DocsWriting 99 25Maintaining 50 10Building a community 40 15Maintaining outdated 10 0Translating 5 5

The ego-rewarding scale goes from 0 to 100: 0 means "Nobody caresabout doing it, why should I?", 100 means "Future obituaries aboutme will mention this great achievement." Generally, writing new codeis nearly twice as motivating as maintaining old one, which is twice asmotivating as writing new documentation.

Caveat: Figures arbitrarily based on my own experience.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 12 / 34

How to make DOCS available?

Figure: Provide docs for (nearly) everything your software does (© xkcd)

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 13 / 34

How to make DOCS available?

Start by writing core documentation yourself: docs is like code,if you are examplar in writing docs people will be inspired andcontributeUse a dVCS like git for your central docs repository andencourage people to submit documentation patches.Ask power-users to document their use of the software.Maintain a list of not-yet-written docs, starting with small items.Use a low-floor-high-ceiling format: plain-text is the way,everyone can read and write it, and it can be converted towhatever you want.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 14 / 34

How to make DOCS usable?

Figure: Think (twice) about what docs your user needs (© xkcd)

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 15 / 34

How to make DOCS usable?

Invite people to comment available docs (and take action.)Remove useless and outdated docs (assume newbies cannot spotthe difference by themselves and will feel lost)"Hire" a docs maintainer. Make sure someone is in charge andeveryone knows about it.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 16 / 34

How to make DOCS discoverable?

Figure: Think (twice) about when your user user needs docs (© xkcd)

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 17 / 34

How to make DOCS discoverable?

Have a central place for publishing your docs. It can be thesame central place that you use for writing docs (e.g. usingwiki), but it is not mandatory (e.g. a git repo for writing docs, awebsite for publishing it.)Make it easy for everyone to share the docs web pages from thiscentral place (e.g. through social networks). Because you wantto make your docs discoverable far beyond your central place.Hire a docs community manager, in charge of the two tasksabove.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 18 / 34

Summary: focus on Your Single Simple Tutorial

Your Single Simple Tutorial (SST) is your main DOCS access point.

Everyone finds it.It is directly actionable and useful to everyone.Someone is in charge and feels proud about maintaining it.Users can easily contribute with ideas on how to improve it.

If you cannot write a Single Simple Tutorial, think what itmeans. If you can write it, put it on top of your prioritiesand go ahead.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 19 / 34

Make it simple: allow plain text documentation

Plain text is directly good for developers: they like it.Plain text is indirectly good for users: plain text can beexported to other formats, users will benefit from the variety ofsupported formats.Plain text is good for everyone because it allows simplecollaboration on the documentation.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 20 / 34

Wait a minute. . . plain text? Really?!

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 21 / 34

Make it collaborative: use a dVCS or. . .

The other advantage of using plain-text based docs is that you caneasily make it collaborative. Some advice:

1 Use git or another good dVCS.2 If you cannot use a dVCS. . . well, try harder using one.3 If you failed, use etherpad.4 If you failed, use a wiki.5 If you failed, go back to 1.

Another option is to consider using a collaborative documentationplatform. The trick is to find a good one, and the good ones areplain-text based, of course.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 22 / 34

Example of a good collaborative documentationplatform

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 23 / 34

Build your own plain-text collaborative setup (1)

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 24 / 34

Build your own plain-text collaborative setup (2)

Worg is a git repository containing plain-text docs about Emacsorg-mode.

http://orgmode.org/worg/ hosts a HTML export of thisdocumentation, but you can also browse the docs from Emacs andexport them to whatever format suits best your needs.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 25 / 34

Ego-reward table with plain-text dVCS docs

Task The Old Way (/100) ASCII/dVCSWriting new docs 25 75Maintaining outdated docs 10 40Translating docs 20 40Translating (outdated) docs 2 10

Yeah! Writing docs is now even more rewarding than maintaining oldcode! And maintaining outdated docs is now easier than writing newdocumentation!

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 26 / 34

Emacs: Docs are directly accessible. . .

Emacs documentation is directly available in Emacs itself: newbiesare one-click away from the tutorial and power users are onekeystroke away from in-depth manuals.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 27 / 34

Emacs: . . . from the welcome screen

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 28 / 34

Emacs: Docs are available in various formats. . .Info manuals: plain text (TeXinfo), HTML, PDF.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 29 / 34

Emacs: . . . for the newbies and the power users.

There is documentation for newbies and power users. Here is a shorttable with relevant docs for each category of users:

Newbies Power UsersTooltips C-h v (variables docstrings)Info manuals C-h f (functions docstrings)C-h t (tutorial) Code and comments are accessibleC-h m (mode description) In-depth and up to date Elisp manualC-h k (keybinding docs) The emacs-devel mailing list

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 30 / 34

Emacs: Docs are collaboratively written.Complementary docs are collaboratively written :http://www.emacswiki.org

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 31 / 34

Power users are key

1 Power-users love to have something to work on: don’t miss theopportunity to tap into their motivation when it comes towriting docs.

2 Also, power-users are often willing to work closely withdevelopers, sharing good plain-text and dVCS practices.

3 Remember: power-users bridge the gap between developers andusers. They are the one who can transform a confused rescuemessage into a constructive documentation bug report.

4 Finally, power users have a realistic perception of the learningcurves and of other users’ various needs, so they are the bestposition to write useful docs.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 32 / 34

Newbies are key: resist saying "RTFM"

Whatever the newbie’s problem is, chances are that it’spartly your problem as well.

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 33 / 34

Thanks!

. . . bzg@altern.org . . .

Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 34 / 34