BSDPG Doc Summit


Introduction by Dru Lavigne

Dru
Warren
Scott
Jim
Hiroki-san
Goto-san
Adam
Benedict
Matt
Gavin
Gabrielle

Ingo Schwarze of OpenBSD wrote:

1. In the base system, make sure that all reference documentation
    is available from man(1).  Adding or changing user-visible
    features without adding or updating manuals is inacceptable.
    Bugs in the manuals are treated with the same kind of diligence as bugs in the code.

 2. The main goals are exactness, completeness, clarity, brevity,
    and simplicity - corresponding to the general goals of the
    project that include correctness, clarity, smallness, and
    simplicity of the code and clarity, smallness, and simplicity
    of the user interfaces.  Actually, clarity and simplicity of
    the user interface and the manual can only be reached *together*,
    not separately.  When the interface is botched or bloated,
    the manual is hopeless.
    To reach these goals, have developers document their own
    code.  Just like in the code, pay attential to detail,
    and pay attention to a consistent style.  For the latter,
    it tremendously helps that one person (Jason McIntyre, jmc@)
    reads every commit to any manual, and tweaks half of them.

 3. Completeness includes that all user and admin utilities,
    all syscalls and library functions, all kernel drivers,
    all file formats and configuration files must have a man
    page, which documents all features intended for use,
    in particular the complete syntax and semantics.  In a
    default install, the goal it to make it hard to find any
    file not documented in a manual; or in dmesg(1) output,
    any driver not documented in a manual.

 4. For new base system documentation, only mdoc(7) format is
    acceptable.  The older formats man(7) and pod2man(1) are
    only supported when tracking upstream projects in base.
    Autogenerating man(7) code is strongly discouraged, both
    because all autogeneration tools notoriously generate
    low-quality man(7) code and for reasons of simplicity and
    maintainability.
    Regarding graphical readability, focus 100% on US-ASCII
    80-column terminal output.  Anything not looking optimal
    in that format is unacceptable and must be changed.
    Non-ASCII characters are strongly discouraged in manuals.

 5. All documentation that is not reference documentation,
    in particular material discussing "What can i use to do X?"
    or "Is trying to do Y a good idea or not, and why?" but not
    "How do i use Z?" belongs in the FAQ on the web site.
    Putting such information anywhere else is strongly
    discouraged.  In particular, people should not set up
    private web sites to "help with OpenBSD" - these almost
    always contain wrong and outdated information.

 6. The FAQ cannot reasonably aim for exactness and completeness,
    so it aims for usefulness and relevance instead (and for
    correctness, clarity, brevity and simplicity, of course).
    While the manuals are updated in -current together with the
    code, the FAQ is updated twice a year for each release.
    Contributions from developers are welcome in this area, too,
    though not required with the same strictness as in manuals.
    Timeliness and a consistent style are assured by Nick
    Holland (nick@).  Again, one person, one style works
    very well, in this area, too.

 7. The most important point about FAQ style is to avoid HOWTO
    style (if you want X, type Y, then type Z).  Instead, explain
    which tools exist, how they should be used in concert, and
    point to the manuals for the exact commands.  Explore variants
    and alternatives and their merits and drawbacks, i.e. in which
    situations they might make sense as well.  Also mention which
    alternative ideas are altogether bad ones for which reasons,
    such that people don't unnecessarily hurt themselves - even
    though some will invariably insist to do so, anyway.

 8. Discourage translation of manuals; it is just impossible
    to attain the required quality.  People *have* to look
    at the real thing in this respect.
    Mildly encourage translation of the FAQ or parts of it
    to lower the language barrier for people trying to get
    first rough ideas: For the FAQ, exactness is not as
    critical as for the manuals.  However, delete translations
    when they become insufficiently maintained and out of date.
    No translation is clearly much better than a wrong or
    outdated translation.

 9. Regarding ports, package whatever is available upstream.
    When there are options, prefer to package and install
    whatever is closest to OpenBSD base system standards -
    that is, mdoc(7) source code when available, else man(7)
    source code if available and of reasonable quality, else
    preformatted manuals for man(1) if they can be generated
    with groff(1), else whatever is available.  If possible,
    avoid info(1), HTML, PostScript or PDF documents.  Never
    ever install docbook(1) input files, and avoid using them
    in the build system if possible, to avoid unreasonable build
    dependencies and excessive build times.

 10. Advertise high-quality books on the OpenBSD web site.
    Do not mention low-quality books even when they are known
    (for example, a very low quality book on PF was recently
    published in German language; do not use it).
    List conference talks by OpenBSD developers on the
    OpenBSD website.
    However, all this must not be required for using the system,
    it is only considered additional background information
    and does not replace proper documentation in any way.

I think Postgres's manual is very high-quality:
http://www.postgresql.org/docs/
http://www.postgresql.org/docs/manuals/

Problem with it:
We have all versions of our manual available on our website.  They're organized by version.  When you search for something, using google or whatever, you may not (in fact, probably won't) get the most recent version of the docs.  It's obvious if you're looking at the URL, and you can change it there, but that's kind of a drag.

Manual is maintained in docbook (heh) and we have a mailing list for discussion/submission of patches.


Topics:
- getting new people involved

- using user groups to get new doc committers?

- how can a monolithic document be changed to a version specific document?

- is something better than nothing or is better to prune outdated stuff?

- dated/obsolete docs vs. having *something* to read

- Versioned documentation benefits and issues/disadvantages (PGSql do this, FreeBSD considering).  Backport issues?

Projects (how they do it now):

PFSense: no reference documentation, book is for previous release, a lot of stub articles (many outdated)  on the wiki; most of the documentation merely repeats what is documented elsewhere.  Not a large amount of doc writers. Tagging system for docs exists but is not used consistently.

FreeBSD: - common problem is that the people who know the material never read the handbook anymore.  need to get all users to read/comment on the handbook
 - would a recognition system (ala forum 'karma' type system) be helpful to attract new people?
 
  - freebsd has a doc primer, somewhat lengthy

OpenBSD: (see above)

PC-BSD/FreeNAS/TrueNAS: - freenas/truenas has version-specific documentation.  not very scalable
- single reviewer, tight control to avoid wiki spam


PostgreSQL: base manual is in docbook, we have several previous versions on the website.  Lots of interesting stuff on our wiki (http://wiki.postgresql.org/wiki/Main_Page), uses Django to allow user comments on doc pages

how do you offer a doc bounty e.g. when is the doc "done"?
GCiN format was successful in defining specific doc tasks
might be able to merge 'karma' ideas with bounties
Achievement unlocked: doc commit bit ;)

youtube video for getting started with documentation might lower the barrier to entry for new documenters

cvs can be intimidating, the process needed to get involved in FreeBSD doc contributing is high (cvsup repo first, then cvs co from local copy, etc).  This could be improved with anoncvs, but subversion is the answer (possibly also git from that?)


dru gets a few people at every conference who want to get involved with documentation

append a free session at each conference on getting started in docs e.g. evening with pizza

getting user groups involved would be very beneficial


instant feedback capability (such as Postgres docs) very promising
Example of somebody reporting an issue through the PG comments mechanism: http://www.postgresql.org/docs/9.1/interactive/libpq-threading.html

very common now for people to submit a bug report (Problem Report) for docs and it goes into a black hole

social networking component?

more approachable "meet the doc team, who we are" on http://www.freebsd.org/docs.html  56 doc commits currently, 119 people in last year have touched docs.  That includes translators.




doc team / doc eng  / actual committers 

last session of a conference day is "what you need to install to do docs", followed by we're heading to hacker lounge to write docs, come join us  (the 'doc sprint' concept), hackers lounge for documentation   [excellent idea!] documentation lounge needs to be on the schedule and explicitly state that dropins are welcome

Pg can involve local user groups in this as well.  Great idea!

A virtual machine for submitting documentation! (used in GCiN to reduce entry barrier) 
http://wiki.freebsd.org/GoogleCodeIn/GettingStarted

http://wiki.freebsd.org/GoogleCodeIn/VMnotes
(bcr send that also to Matt from iXsystems for him or his marketing team to try out)


Action items:

update this page: http://www.freebsd.org/docproj/submitting.html once svn convert is complete

GCiN VM image worked well for new committers.  Gavin to update the vm image (about a day's worth of work) and we could somehow provide this more officially? Doc jail maybe?

doc sprint in a local repo

the 'doc lounge' idea for upcoming conferences - come in a get a doc fixed while you wait (pizza and beer?)beer, yes. (but only in europe - pizza in N.A.)

if NYC*BUG model works, can be demonstrated to other user groups -- matthewstory@gmail.com to keep group up to date on progress

Look into lokalize, the tool KDE use for translations. http://userbase.kde.org/Lokalize

Upcoming conferences:

(will all conferences have an openetherpad or similar?) we always use openetherpad as it is free, often have people come in on skype if Internet is decent, also do IRC channel for project specific events, e.g. #bsddocs on Efnet
We also want to have a port for Etherpad, so we can host our own pads. See http://wiki.freebsd.org/WantedPorts


http://openhelpconference.com/ Cincinatti, August 10-12, we have a room already for a docsprint on August 13

Cambridge DocSummit: no URL yet, ~Aug 29-31, can negotiate space for doc stuff

EuroBSDCon: wants a presentation/tutorial on documentation, can negotiate a space for doc stuff
*** gavin@ & bcr@ to submit half-day tutorial proposal, for afternoon session, convert into DocLounge at end of day.  Then convert the half-day tutorial into a standard 1-hr conference talk to be delivered regularly for ~1 year???

NYCBSDCon: no date yet, will have 1 day con which can have a docsprint a day before/after (some time in fall?)

MeetBSD: Mountainview, CA, URL will be meetbsd.com, some time in November, can have a day for a doc event 

Afternoon stuff:

http://translate.sourceforge.net/wiki/virtaal/features .po file editor

PDF has not been built in over a year (HTML generated almost daily).  Other formats can probably be dropped: n>0 complains about out-of-date PDF, n=0 complains about other formats. - bz@ going to look into this

Some tools in the Ressources section we might want to try out: 
http://everythingisdata.wordpress.com/2012/05/07/scripts-for-writing-papers/

Just to toss it in the ring, has anyone considered asciidoc as a document base and generate all the other formats from it? I've been looking at it and it has a lot of appeal to me, it generate pretty much any output you might want including epub as well as man page, pdf, etc. I generated the manual as an epub when I first ran across it and the output was very good.  http://www.methods.co.nz/asciidoc/

tag aware editors--good to mention in doc tutorial talks

1 SGML editor remaining, many XML editors; if user has option of editor, need a list of reqs editor/cleanup tool must do to adhere to published style guidelines (fdp primer in a nutshell)

Once we are in XML DocBook world:
investigate xml diff tool, xml lint tools
http://diffxml.sourceforge.net/ (WARN: no declared license)

user group conference? document how to start a user group

next doc sprint: tentatively June 23 (Saturday) bcr@ will email list to see if OK date