production of Varnish Documentation

[Poul-Henning Kamp]

I have spent some time since VUG2, checking out how various open source
projects have dealt with documentation, and I have reached a conclusion
which I will share with you in a moment.

The first school of thought on documentation, is the one we subscribe
to in Varnish right now: "Documentation schmocumentation..."  It does
not work for anybody.

The second school is the "Write a {La}TeX document" school, where
the documentation is seen as a stand alone product, which is produced
independently.  This works great for PDF output, and sucks royally
for HTML and TXT output.

The third school is the "Literate programming" school, which abandons
readability of BOTH the program source code AND the documentation
source, which seems to be one of the best access protections
one can put on the source code of either.

The fourth school is the "DoxyGen" school, which lets a program
collect a mindless list of hyperlinked variable, procedure, class
and filenames, and call that "documentation".

And the fifth school is anything that uses a fileformat that
cannot be put into a version control system, because it is
binary and non-diff'able.  It doesn't matter if it is
OpenOffice, LyX or Word, a non-diffable doc source is a no go
with programmers.

Quite frankly, none of these works very well in practice.

One of the very central issues, is that writing documentation must
not become a big and clear context-switch from programming.  That
precludes special graphical editors, browser-based (wiki!) formats
etc.

Yes, if you write documentation for half your workday, that works,
but if you write code most of your workday, that does not work.
Trust me on this, I have 25 years of experience avoiding using such
tools.

I found one project which has thought radically about the problem,
and their reasoning is interesting, and quite attractive to me:

	1. .TXT files are the lingua franca of computers, even if
	you are logged with TELNET using IP over Avian Carriers
	(Which is more widespread in Norway than you would think)
	you can read documentation in a .TXT format.

	2. .TXT is the most restrictive typographical format, so
	rather than trying to neuter a high-level format into .TXT,
	it is smarter to make the .TXT the source, and reinterpret
	it structurally into the more capable formats.

In other words: we are talking about the "ReStructuredText" of the
Python project.

Unless there is something I have totally failed to spot, that is
going to be the new documentation platform in Varnish.

Take a peek at the Python docs, and try pressing the "show source"
link at the bottom of the left menu:

(link to random python doc page:)

	http://docs.python.org/py3k/reference/expressions.html

Dependency wise, that means you can edit docs with no special
tools, you need python+docutils to format HTML and a LaTex
(pdflatex ?) to produce PDFs, something I only expect to happen
on the project server on a regular basis.

I can live with that, I might even rewrite the VCC scripts
from Tcl to Python in that case.

Comments, inputs... ?

Poul-Henning

-- 
Poul-Henning Kamp       | UNIX since Zilog Zeus 3.20
phk at FreeBSD.ORG         | TCP/IP since RFC 956
FreeBSD committer       | BSD since 4.3-tahoe
Never attribute to malice what can adequately be explained by incompetence.