The Four Letters Word of FLOSS: DOCS
Upcoming SlideShare
Loading in...5
×
 

The Four Letters Word of FLOSS: DOCS

on

  • 946 views

Some thoughts on how to encourage developers and users of FLOSS softwares to write good documentation more easily.

Some thoughts on how to encourage developers and users of FLOSS softwares to write good documentation more easily.

Based on a talk I gave at OLPC EduJam in Montevideo, May 2011

Statistics

Views

Total Views
946
Views on SlideShare
910
Embed Views
36

Actions

Likes
0
Downloads
1
Comments
0

2 Embeds 36

http://lumiere.ens.fr 32
http://bzg.fr 4

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

The Four Letters Word of FLOSS: DOCS The Four Letters Word of FLOSS: DOCS Presentation Transcript

  • The Four Letters Word of FLOSS: DOCS Bastien Guerry October 2011Bastien 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 to think 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 documentation 2 Try to make it useful for many users 3 Try to make it easily discoverableThis, 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 applicationHypothesis: 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 gapHypothesis: 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 applicationsHypothesis: 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 features 2 Then encourage good communication between users and developers 3 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 BeastThe beauty A community of users/developers (probably with a high power-users/developers ratio) efficiently communicating with each others, writing plain text docs (from tutorials to full-fledged manuals) collaboratively for a specific and standalone tool with a stable set of features, these docs being 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 few power-users; documentation is written in various non-ascii formats and scattered through the web (surely not accessible from the software itself) and there are only 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 Docs Writing 99 25 Maintaining 50 10 Building a community 40 15 Maintaining outdated 10 0 Translating 5 5The 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 and contribute Use a dVCS like git for your central docs repository and encourage 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 to whatever 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 spot the difference by themselves and will feel lost) "Hire" a docs maintainer. Make sure someone is in charge and everyone 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 the same central place that you use for writing docs (e.g. using wiki), but it is not mandatory (e.g. a git repo for writing docs, a website for publishing it.) Make it easy for everyone to share the docs web pages from this central place (e.g. through social networks). Because you want to make your docs discoverable far beyond your central place. Hire a docs community manager, in charge of the two tasks above. Bastien Guerry () The Four Letters Word of FLOSS: DOCS October 2011 18 / 34
  • Summary: focus on Your Single Simple TutorialYour 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 be exported to other formats, users will benefit from the variety of supported formats. Plain text is good for everyone because it allows simple collaboration 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/dVCS Writing new docs 25 75 Maintaining outdated docs 10 40 Translating docs 20 40 Translating (outdated) docs 2 10Yeah! 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 Users Tooltips C-h v (variables docstrings) Info manuals C-h f (functions docstrings) C-h t (tutorial) Code and comments are accessible C-h m (mode description) In-depth and up to date Elisp manual C-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 the opportunity to tap into their motivation when it comes to writing docs. 2 Also, power-users are often willing to work closely with developers, sharing good plain-text and dVCS practices. 3 Remember: power-users bridge the gap between developers and users. They are the one who can transform a confused rescue message into a constructive documentation bug report. 4 Finally, power users have a realistic perception of the learning curves and of other users’ various needs, so they are the best position 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