Thread: OpenBSD Newbie!
View Single Post
Old 16th July 2013
ocicat ocicat is offline
Administrator
 
Join Date: Apr 2008
Posts: 3,318
Default

Quote:
Originally Posted by Majorix View Post
I cannot cross out ALL the user-contributed documents, but one gets more and more experience everyday helping picking out the rubbish.
You may be overlooking cultural differences. The OpenBSD developers put significant importance on the quality of its manpages as being the definitive source of truth next to the source code itself. Hence, these pages are what users should search through first to find out the intentions, usage, & shortcomings of the various utilities & functions provided in a base installation. The OpenBSD community discourages how-to's for exactly the reasons jggimi outlined above. Because long time users understand the project's philosophy about documentation, most will shy away from creating documentation unless there is a specific reason for doing so.

This will also indicate who it is that is writing non-sanctioned OpenBSD documentation -- those who don't understand the project, its goals, nor the need to keep the documentation centralized. No one is guaranteeing its veracity, so it is anyone's guess as to whether it is correct, up to date, & inclusive enough to address the differences readers will have in their own configurations.

Maybe you are coming from the Linux tradition where the kernel is created by one group, & userland utilities and user applications come from elsewhere. Who owns the documentation is not entirely clear to that community, & the result shows. The "how-to" culture is a bandage which does not address the fundamental problem & need of that community. "How-to" documents promote sloppy thinking, short-cutting real understanding, & general problem-solving. "If I only look a little longer, someone will have fixed my problem without knowing my situation, & I don't have to bother figuring it out for myself".

Then something will eventually break where you will need to troubleshoot the whole mess. Good luck.

Save yourself some time & aggravation by studying what documentation the project provides first. The discipline will serve you well in the future, & you may very well find a better solution faster.
Reply With Quote