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