A reminder with OpenBSD
The documentation is great, and over the last decade I've gotten very used to being able to read man pages and figure out how to do whatever I want.
Unfortunately, very few other projects regard documentation as nearly as important, and as I start setting up a Subversion repository for a few personal projects, I'm reminded of this fact. How do you set up an svn server to use encrypted channels for security purposes? Well, if you read the man pages, it's pretty clear that you can't. You can, of course, but you have to read through the Subversion book to find any of that info - some of it directly contradictory to the man pages. In addition, just to be extra helpful, there is an online book for TortoiseSVN, a graphical Subversion client for Windows, that covers many of the same topics. Who knows when it will contradict the main Subversion book?
I'm glad they've got a book, but that kind of inconsistency leaves one wondering... is the book always authoritative? Clearly the man pages aren't always, but they might be for some things, and I'm left feeling like I have to check multiple sources of documentation, and then test every little thing to see which document is accurate. I'm tempted to instead just start reading the source to figure out what actually happens.
Unfortunately, very few other projects regard documentation as nearly as important, and as I start setting up a Subversion repository for a few personal projects, I'm reminded of this fact. How do you set up an svn server to use encrypted channels for security purposes? Well, if you read the man pages, it's pretty clear that you can't. You can, of course, but you have to read through the Subversion book to find any of that info - some of it directly contradictory to the man pages. In addition, just to be extra helpful, there is an online book for TortoiseSVN, a graphical Subversion client for Windows, that covers many of the same topics. Who knows when it will contradict the main Subversion book?
I'm glad they've got a book, but that kind of inconsistency leaves one wondering... is the book always authoritative? Clearly the man pages aren't always, but they might be for some things, and I'm left feeling like I have to check multiple sources of documentation, and then test every little thing to see which document is accurate. I'm tempted to instead just start reading the source to figure out what actually happens.