[Nix-dev] Yet Another idea About the Wiki

[Martin Vahi]

I'm one of those people, who is new to Nix and
is trying to learn it. What regards to the idea
of killing the wiki, then I suggest that You
just make a wiki that is editable only to
the people, who have been with the project for
a long time and know, what they are writing about.

Once upon a time, years ago, at one of my jobs
we solved the problem so that we had an internal
wiki that only the core developers could edit
and then the rest, PDF/static-HTML/whatever that went
to the end users, was automatically generated
from that wiki by the release team. The generated
documentation was bundled with the application,
like at the old times on Windows, where each
application had a Help menu with documentation, except
that in stead of the Windows CHM-files the application
launched the default web browser with a local file
URL to the static, bundled, HTML.

It worked fine. Everyone were happy, even the
ones that wanted to print PDF-s.

There were 2 types of documentation: the "tutorial"
and the API doc. In the case of the API doc we used
special syntax that was used by the application
for showing the documentation dynamically, at its
proprietary IDE.

We actually made quite many iterations before
coming up with the wiki based solution and the
end result worked like a charm. :-D

Of course, the difficulty is the modification of the
wiki software, but, life is tough, so that just has
to be lived with.

With a hope of being useful,
Martin.Vahi at softf1.com