Subject: 7 points user's memo (was why XML?)
To: NetBSD Documentation Discussion List <netbsd-docs@NetBSD.org>
From: =?UTF-8?B?UHJ6ZW15c8WCYXcgUGF3ZcWCY3p5aw==?= <firstname.lastname@example.org>
Date: 04/02/2007 01:36:32
Content-Type: text/plain; charset=UTF-8
On Sun, 01 Apr 2007 19:25:32 -0400
"Greg A. Woods" <email@example.com> wrote:
> If one wants clearly readable, easily maintained, easily parsed,
> structured documents suitable from everything from business cards to
> entire books, then Lout really is the best thing I've seen to date
> (and I've been looking at and for such tools for decades now).
> HOWEVER, for NetBSD, with a _heavy_ investment already made in mdoc(7)
> formatted documents, I would be quite happy to stick with that. We
> already have groff maintained in-tree, and we'll need it for the
> foreseeable future anyway. It's easy enough to use and it is very
> well understood too.
The whole disscusion on NetBSD documentation was branched into
several topics nearly from the begining. Now I understand we went
thru following salient point:
1) wrong WWW layout
2) outdated docu-pages
3) weak cooperation with community
4) unefficient docu-page creation tools
A lot of steam was released but we are still in the same dock. This way
we can argue for ages.
Could someone summerize what convenient tools for XML (present),
nroff/mdoc (former), and Lout (recommended) formats available for
NetBSD user willing to write docu-pages? When I write docu-pages I
think not only strict netBSD documentation but articles, and algorithms
for doing this'o'that as well.
My questions are:
1) do we take the status quo for granted?
2) in what field (4 points above) can we succeed soon?
3) is there any "strategy" for improvements being pondered by WWW Team
(I used big letters purposely to match it against Wiki Team)?
4) new ideas emerged, what about them?
Apart from the above text I'd like to submit another idea of mine. But
let me say first that we ended now with no changes. In other words if
someone wants to write let him write. Only after that "we" will think
(e.g. WWW Tem or Wiki Team) were to pigeonhole the text.
A few days ago Jeremy C. Reed created new page in Wiki. Sporadic, ad
hoc activity tailored to suddenly emerging circumstations aka needs.
But without vision for Wiki or NetBSD docu as a whole. No wonder some
of you (me for sure) are discourage to write. Where, what, in what
I can create new WWW with NetBSD contents ina few days. It's no problem
as I designed and created numerous WWWs (back from OS/2 Warp times).
But what for? For personal glory? That's why I started the disscussion
about doc issues seeing places where it could be improved.
For the last time I suggest you a change. No threat, but result of my
discouragement. What about Great NetBSD Docu Division? What's that?
Namely (the sequence is important):
1) "WWW Team" and "Wiki Team" will be "formally" elected (with
common sense on mind of course :-) ) with __member names available to
2) WWW Team and Wiki Team will declare mutual help signed on highest
From: Lasse Hillerøe Petersen <firstname.lastname@example.org>
Subject: Re: Proposition for Releases page changes
Date: Sat, 31 Mar 2007 10:35:01 +0200 (CEST)
> We don't need a dumbed down NetBSD for desktop users. What we need is
> better documentation of how to customise a NetBSD+pkgsrc installation
> to make a good desktop system. Or a good Mail/Web/Database/File
> server. Or a good laptop system. Or a good virtualization system. And
> so on. I think this could be a(nother) place where NetBSD could
> distinguish itself from other systems.
> I have been thinking for some time about whether I could set up a
> machine with Xen, running WindowsXP, NetBSD and Linux, and perhaps
> also some TV-tuner hardware. I have hesitated, because I know I will
> not succeed without help. Lots of help. But if I could have a "free
> pass" for asking the experts about all the "stupid" problems that
> will pop up, in return for a commitment to produce a detailed report
> about my experience, including a step-by-step how-to, I might
> consider it an interesting challenge. The report could then be
> reviewed by the "tutor" developers before being published on the
> NetBSD website, probably in a special "User Report" or "NetBSD Best
> Practices" section.
3) A lot of pages from Gallery will be moved to Wiki leaving the place
for official documents only.
4) All hostilities between WWW and Wiki will stop immediately. Links to
Wiki will be placed on official WWW were needed or suggested by Wiki
Team (__as users know better what they want to see on NetBSD WWW__).
5) Developers and programmers (or WWW Team) will determine weak points
in NetBSD Docs and will start to improve the situation. The call for
help from community will be issued (also as a form of invitation and a
sign of ceasetions of hostilities ;-) ).
6) WWW Team will
a) determine ultimate docu-page creation tools used by developers and
b) create page describing efficient usage of the tools
c) treat Point 7, specially point b) with outmost importance.
7) WWW Team and Wiki Team will create guidlines for future
development/improvement NetBSD Documentation.
What do you think about it?
Przemysław Pawełczyk <email@example.com>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (NetBSD)
-----END PGP SIGNATURE-----