[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Document Project] OpenBSD Documentation Explained.



I'm trying to improve the state of OpenBSD documentation when I have time
to do that. I'm afraid I'm responsible for what `man -k' says these days...


My main interest lies in documenting the porting process, how packages
work, and how to write new ports right the first time, so that I don't
have to fix a lot of little details later. Yes, I'm lazy :)


Guess what my main problem is ?

We already have too many resources that document how ports work !
Most are not quite accurate. Sending people off to the FreeBSD handbook
like we do is not such a hot idea any more, as we do a lot of things
differently than they do now.

Having a few html pages that say the same thing again and again does not
help.

Having comments at the top of bsd.port.mk that are duplicated all over the
place does not cut it either.

So guess what I do when I have time ?


That's correct: I remove redundant pieces. My aim is to end up with only
a few REFERENCES documents (like the ports(7), packages(7), bsd.port.mk(5)
manual pages) and a good FAQ as to how to write new ports, with much LESS
redundancy than there currently is.

Otherwise, what happens is that each time a detail changes, or a new sound
rule is discovered to help porters, it's only documented in one place, and
I forget about the three other `logical' places where people will look.

Whereas, with only one `logical' place that is non-empty, and all other
logical places being actually pointers to the RIGHT place, this would not
happen.

BTW, you can just forget about lots of people pitching in to do
documentation. Last time I tried to get people involved (in overseeing
the ports mailing-list and coordinating stuff, totally non-technical,
easy job), I ended up with over ten candidates, none of which has actually
done more than a token effort at running it.




Visit your host, monkey.org