Home > FreeBSD > FreeBSD Documentation: An Interview with Tom RhodesFreeBSD Documentation: An Interview with Tom Rhodes Submitted by FreeBSD_User 2004-10-14 FreeBSD 34 CommentsFreeBSD has been known for excellent documentation and here is a rare sneak peak behind the scenes of the FreeBSD document project with FreeBSD’s very own Tom Rhodes.About The Author Eugenia LoliEx-programmer, ex-editor in chief at OSNews.com, now a visual artist/filmmaker.Follow me on Twitter @EugeniaLoli 34 Comments 2004-10-14 2:19 am What’s the best bsd for running on a p2 desktop computer with 64mb ram? And is there a live CD available? 2004-10-14 2:53 am and this becomes even more aparent when compared to Linux. I don’t say that there aren’t good documents of some Linux components/aspects/feature, but the quality is extremely uneven. FreeBSD’s documentation is often compared with Linux’s, and that’s what makes it stand out even more.Solaris is well-documented, like FreeBSD, but people here are not as aware of this, since less often is a Solaris user a Linux user at the same time. FreeBSD and Linux get compared to each other more often.One interesting thing to note: if I need help with a certain command, configuration procedure or administrative procedure under FreeBSD or Solaris, all i have to do is type in the question in gogle, and my answer is always among the first 10 hits. Not so with Linux: the search would bring up page after page of some kernel discussion, or other unrelated dis cussion. Sometimes you find a helpful link within the first 3 pages, but often you have to search longer. That shows that, even IF there was some good document on the issue, people just don’t know that and/or don’t link to it. That’s why, even god, wel-written Linux docs, are not as useful as they could be. Drawning in a sea of noise and lacking docs.My conclusion: more people don’t necessarily create a well documented operating system. A few good men make all the difference.BTW, the FreeBSD Handbook is really sweet! Have a look at it, even if you don’t use FreeBSD. 2004-10-14 4:05 am The only Live CD for any *BSD I know is http://www.freesbie.org/ which is a live CD for FreeBSD. I believe it is for the 4.x branch. There has been only one official release as far as I know. Though, I don’t think there is much of a reason for it. The biggest differences in *BSD vs Linux are under the hood; but then again I guess it can’t hurt. Especially in terms of hardare compatibility or to test scripts on or something. 2004-10-14 4:52 am in the Open Source software world. Pretty much everything is covered in the Handbook. The FAQ is great too. The online documentation (man pages) is fantastic as well. Even the scripts are well commented.BSD in general has pretty good documentation, but FreeBSD’s documentation really stands out. The Handbook is very well laid out and easy to follow. That’s one of the winning points. You can practically print it out and follow it step by step from install to administration.The other BSD’s should follow in FreeBSD’s footsteps when it comes to documentation. Theirs might be good, but IMHO FreeBSD’s is clearly better.There is only one thing I do wish for. I wish there were more advanced BSD related books. Preferably, more advanced administration handbooks. Kinda like a heavy duty administration cook book type of thing. Guides to showing how to set things up for corporate enviroments and heavy duty Internet server type of work. Guides for setting up a secure corporate Internet server using BSD would be nice too.Most the BSD related books are introductory. I would like a books for those that already know BSD (so they can totally skip the installation chapters) but want more out of it. You know what I mean?Anyway, keep up the good work FreeBSD team!! Let’s also hope for a -STABLE branch soon too. 2004-10-14 4:58 am OpenBSD’s documentation is far better 2004-10-14 5:37 am FreeSBIE (http://www.freesbie.org/) is a “live” bootable release of FreeBSD 5.2.1, although betas for 5.3 are available by bittorrent.Also, there are live CD snapshots ov 4.x, 5.x, and even 6.0-CURRENT at http://snapshots.se.freebsd.org/i386/ISO-IMAGES/None of the live FreeBSD distributions are as user-friendly as Knoppix, but if you read the documentation, they will provide as nice quick way to evaluate FreeBSD on your hardware.FreeBSD 5.3 beta7 (ftp://ftp.freebsd.org/pub/FreeBSD/ISO-IMAGES-i386/5.3/) should run fine on your Pentium II, as long as you stick with a lightweight desktop environment like FluxBox, or WindowMaker. KDE or Gnome will probably be painfully slow. If you want to simply learn FreeBSD as a server, then you don’t need to run a desktop at all, and all standard server apps should run fine on your hardware. The reason I recommend the beta version of 5.3 is that it is very near production release, and I have noticed it runs quite well on slower hardware–much faster than version 5.2.1. 2004-10-14 6:30 am I’ve always liked how I can access easily the man pages from Open,Free, and Net BSD websites. 2004-10-14 6:48 am Documentation is the most important thing of all, when it comes down to the matter of using software or software libraries. 2004-10-14 7:26 am Tom Rhodes seems to have a personal agenda to push against the DragonFlyBSD developers (specially David Rhodus). It would be nice if he and his friends DES and Bosko stopped doing that. The fantastic 4 (the former three + Poul-Henning Kamp) have alienated a lot of people already and deprived FreeBSD of valuable contributors. 2004-10-14 8:43 am I always love to see what happens behind the scenes of various projects. I have used the FreeBSD Handbook on numerous occasions, tis a life saver. The amazing thing is that it just keeps getting better all the time. Constantly being added to and new features being documented.It is something like 871 pages by now with each chapter / subchapter being laid out it easy to read consise manner. No searching for the latest how-to. Look at the handbook and find the chapter in question. Its that easy.I think being a writer might be a thankless job….. Just want to drop a line to the doc staff and say ” Your efforts are GREATLY APPRECIATED”. The docs are 2nd to none.FYI: The doc team also manages the man pages too. Thats a ton o’ work. 2004-10-14 8:44 am if theres anything i love in FREEBSD is the DOCUMENTATION!looking at fbsd docs comparing to tldp or others, like distro own breeds (gentoo’s recall me) is definetly an asset for BSD, and the FreeBSD project.The layout, the topics and the explanation of the problems, the colors, the simplicity ( not always:D ) is by far now a freebsd brand that many users get identified with! 2004-10-14 8:44 am And this was mentioned in the article where?If you want to make claims that the article does not link to then please provide some facts/links to back it up. Otherwise it is just considered as opinionated slandering.Yes I do follow some FreeBSD mailinglists. 2004-10-14 8:44 am You must be that guy from slashdot.Hey, why do you always link to http://www.des.no and random bogus URLs on it? 2004-10-14 8:52 am Some on mention “looking for Live CD’s”http://www.livebsd.com/http://www.freesbie.org/http://bsdeviant.unixpunx.org/http://livecd.sourceforge.net/The best *bsd for a pII? Depends on what your doing with it. All the *BSD have their niches. Ask yourself, what do you want to do with that pII? Sorry, wish I could be of more help. 2004-10-14 8:57 am Now, what is this FUD?Bullsh*t like this is defaming both FreeBSD and DragonFlyBSD.Go learn to code, instead of uttering nonsense. That would prevent you from looking like a hateful clueless frustrated lamer. 2004-10-14 10:34 am It would be nice if he and his friends DES and Bosko stopped doing that.Oh, our new (FreeBSD devs are eviiil) slashdot troll is back. First it was DES and PHK. Then Baldwin. Now even doc people have an ‘agenda’ against DragonFly. I tell you what: the whole world has an agenda against DragonFly, and personally Matt. Booo.See: http://bsd.slashdot.org/comments.pl?sid=124596&threshold=1&comments…He also posts the same kinda messages in almost all BSD related announcments (even the NetBSD RC announcments on ./ are full of these FreeBSD devs are evil kinda crap). 2004-10-14 11:07 am Having good online documentation doesn’t mean you can slack out simple things.I more than often find the lack of ‘-h’ or ‘–help’ options or when they exist the general uselessness of them annoying. The more than often obscure man pages that make sense to a pro-user of the particular command that make little to no-sense are also a source of frustration. This is not a problem confined to FreeBSD, but I find myself more frequently having to google for things that I feel I really shouldn’t have to. I also find the ‘Read-The-Friendly-Manual you lazy peace of shit’ attitude displayed by many people in the FreeBSD community utterly offensive. It really sad when I hunt down a the exact question I was after on a mailing list archive and finding the a single ‘RTFM’ response.Linux may not have the best documentation in the world and GNU info is a lame replacement for man but I feel that when I’m goggling for a problem Linux related matters give me less hostile reading. And Linux docs aren’t that bad. Most of the major distros keep their own set of docs which can come in handy now and then. TLDP (http://www.tldp.org/) has a lot of good stuff to read and the quantity of it is far more greater than the FreeBSD doc project.Having said that I agree that the FreeBSD Hand book is a very good source of info, the doc project is a nice source of information and howtos.So I hope the Hand book people keep up their good work and other developers and shame on those who slack out on their own docs and relay on others to write howto for them. 2004-10-14 11:16 am I also find the ‘Read-The-Friendly-Manual you lazy peace of shit’ attitude displayed by many people in the FreeBSD community utterly offensive.Where do you see that attitude??? I came to FreeBSD a year ago, and my background was Mandrake and PcLinuxOnline. So you can imagine that I was accustomed to a relatively newbie friendly community.And when I came to freebsdforums.org, I was pleasently suprised. What you claim is a damn lie if there is any. Or, you must have been extremely unlucky. Check out the forums and you’ll see that there is no such attitude there. Sometimes people are directed at the handbook or the manpages, but almost always in a polite manner. The FreeBSD community is one of the friendliest (for noobs and advanced users alike) community. Heck, they even help users with linux problems in their linux section! 2004-10-14 11:22 am Well when I started with FreeBSD I found the man pages and handbook quite useful. I’m not saying I never ever searched for something on the net, but the docs are pretty good.As for the *’Read-The-Friendly-Manual you lazy peace of shit’ attitude displayed by many people in the FreeBSD community*I dont know where you’ve been visiting, but I find the community (especially on the freebsd mailing list, where you can ask ‘newbie’ question) one of the most polite and adult communities around. In fact the ‘Read-The-Friendly-Manual you lazy peace of shit’ posts are rarely seen and if they do pop up such posters are always informed that that is not the preferred behavior in the community. 2004-10-14 1:14 pm Anyone else see that?behind________________________ 2004-10-14 2:11 pm I’m using konqueror 3.3 on kde 3.3.0 (on freebsd), page seems fine, what version are you using? 2004-10-14 2:49 pm On a side note, I have switched ALL of my Linux production servers to FreeBSD and there has been a significant improvement. Backups to the samba server used to take 10 hours for 15 gigs! Now with FreeBSD(No X) and samba 3, folder access and copying has had a significant improvement. Because of the great documentation and easy to use setup all my production boxes are much faster and more secure. Thank you FreeBSD 2004-10-14 4:02 pm “OpenBSD’s documentation is far better”I’m not sure if that’s a troll or an honest opinion.I use OpenBSD as well. I’m awaiting the FTP release of version 3.6. Yes, I know. Bad me! I should have bought the CD. Maybe next time.Anyway, the OpenBSD documentation is good. I’m not saying that it’s bad. Although, there is always room for improvement. It is also my opinion that FreeBSD’s documentation is just a notch better.Compare the two:http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/http://www.openbsd.org/faq/index.htmlThey’re similarly laid out and presented, but I still prefer FreeBSD’s documentation. Seems easier to read and follow. 2004-10-14 4:52 pm I am using 5.2.1 release. I was using samba 2 and Linux mandrake 10. I love how all the services are turned off and you have to go edit your inetd.conf to enable them. The company I work for is CRAZY about security. Having a server that passes all internal network server audits is great. 2004-10-14 5:28 pm Could you provide more details about your experience with FreeBSD?I take the chance to remind you that the mailing listshttp://www.freebsd.org/support.html#mailing-listabd their archives should be a great option to integrate the already excellent documentation. 2004-10-14 6:01 pm Could you provide more details about your experience with FreeBSD?I won’t be saying anything new. As the BETA number was increased, none of the bugs were fixed and new ones were introduced. usb joypads stopped working around BETA5. They posted a workaround (enable debug output). usb printing stopped working too. The gvinum issues are still there after 7 betas. The bug has been there for months. SCHED_ULE was blamed for problems that were mainly due to PREEMPTION. I love FreeBSD, but 5.3 is (with the exception of 4.0-R) the worst FreeBSD release I’ve ever used. 2004-10-14 7:03 pm “I won’t be saying anything new. As the BETA number was increased, none of the bugs were fixed and new ones were introduced. usb joypads stopped working around BETA5. They posted a workaround (enable debug output). usb printing stopped working too. The gvinum issues are still there after 7 betas. The bug has been there for months. SCHED_ULE was blamed for problems that were mainly due to PREEMPTION. I love FreeBSD, but 5.3 is (with the exception of 4.0-R) the worst FreeBSD release I’ve ever used.”I’m just wondering how you managed to play around with 5.3 to judge that it is the worst since 4.0-R. If you are talking about BETA releases, I would first suggest understanding what the term Beta means in software development and then start talking. Why don’t you try this? Wait for the release to happen first and then use it and see how it is. 2004-10-14 7:08 pm I won’t be saying anything new. As the BETA number was increased, none of the bugs were fixed and new ones were introduced.What you’re stating is obviously false. Not only according to common sense (what’s the point of making BETA releases if not to test bugs fixes?), but according to the various release notes. The last one (BETA7) is herehttp://lists.freebsd.org/pipermail/freebsd-current/2004-October/039…where you can see that the known issues list has reduced to just a couple of items (for which fixes are being tested right now).[snip]I love FreeBSD, but 5.3 is (with the exception of 4.0-R) the worst FreeBSD release I’ve ever used.You’ve not yet used it, for the obvious reason that FreeBSD 5.3 isn’t out yet.When using a BETA release, bugs (even major ones) should be expected – that should go without saying. Plus, IMHO, it would be far more *serious* to suspend the judgement until a final release gets out. 2004-10-14 10:36 pm I love FreeBSD, but 5.3 is (with the exception of 4.0-R) the worst FreeBSD release I’ve ever used. I love FreeBSD, and have been using it exclusively for servers since version 3.2 (and exclusively for workstations since version 4.8). And I have to say that 5.3 beta is looking like it is on its way to being one of the BEST releases I have seen for a long time. You nit-pick at a few bugs, most of which are edge cases and definitely not show-stoppers for the majority of FreeBSD users. Of course there are bugs, but you are choosing to *omit* the many new developments that far overshadow any lingering bugs. Besides all the performance enhancements for threading/locking, the ports system has really gotten into gear, keeping FreeBSD users supplied with nicely up-to-date, integrated apps. Also there are many other userland-related improvements–too many to mention. It all adds up to a nicely improved server and a *greatly* improved desktop for FreeBSD. And lastly, getting back on-topic, the documentation team is doing an incredible job keeping pace with all this. Enough with the naysaying. My laptop and workstation are running 5.3 B7 as we speak, and running significantly faster and stabler than 5.2.1 on the same hardware. Of course my servers will not be migrating to 5.3 so soon, but I am fairly sure that within a couple months after full release, I will be moving at least one server over to 5.3, and see how things go before hopefuly moving the others over. 2004-10-14 10:42 pm “This is not a problem confined to FreeBSD, but I find myself more frequently having to google for things that I feel I really shouldn’t have to. I also find the ‘Read-The-Friendly-Manual you lazy peace of shit’ attitude displayed by many people in the FreeBSD community utterly offensive. It really sad when I hunt down a the exact question I was after on a mailing list archive and finding the a single ‘RTFM’ response.”I have been using FreeBSD since 4.6 and started subscribing to the mailing lists around 4.8r. I can say honestly my FreeBSD skill has gone up base on actions/interactions with the FreeBSD mailing lists. I have never encountered anything hostile with respect to the mailing lists. Just curious, “what shouldnt you have to google for?” please provide some examples. It is quite rare to see know response on the mailing lists. I think I have only see that 2 or 3 times in the last 2 years that I have been on the list.“Linux may not have the best documentation in the world and GNU info is a lame replacement for man but I feel that when I’m goggling for a problem Linux related matters give me less hostile reading. And Linux docs aren’t that bad. Most of the major distros keep their own set of docs which can come in handy now and then. TLDP (http://www.tldp.org/) has a lot of good stuff to read and the quantity of it is far more greater than the FreeBSD doc project. ”1) GNU man pages are an excellent source of information. They are the friendliest that I have seen.2) INFO does have some good documentation in it. They are an enhancment to the man page.3) I dont rememeber anyone saying that the Linux doc’s are bad (I could be wrong).4) No one said that TLDP doesnt have a great set of information.With respect to TLDP: “the quantity of it is far more greater than the FreeBSD doc project”Well, I have never had a desire to compare the quantity of pages between both projects. Why is this an issue? Who has more doc’s? Sun/Solaris has 2 compressed 300-400 meg images for their documentation. I have yet to see any project or any other company compete with that. Now, why did I throw that it in? No, reason, its pointless. In essence, “who’s car is faster”? Define faster, would that be in a 1/4 mile vs. mile vs top end. Who’s house in nicer? Define nicer? This debate can go on with no real answers? I certainily debate that fact that those could be consider questions despite that fact that it show some sort of gramatical adherance.DISCLAIMER: I use FreeBSD, Linux (Debian, RH) and Solaris 8/9 and MS since 1980. I spend more of my time using FreeBSD than any other OS (outside of work). 🙂 2004-10-15 3:02 am FreeBSD has had a LiveCD since at least 3.0, if not before. CD2 of every FreeBSD release since 3.0 (the first one I have) is a full-blown, live install of FreeBSD. It’s labelled as a Fixit CD. When you boot off it, you get the same sysinstall as the install CD. Just select the Fixit option and you’ll be dropped to a csh prompt. You now have a full-blown, console-only, FreeBSD system.Been using this as a rescue CD since 4.0. Works nicely. Yes, FreeSBIE and Knoppix and the like are nice for actual use, giving you a full-blown GUI and all, but CD2 is enough for rescue operations and testing console apps. 2004-10-15 3:12 pm “2) INFO does have some good documentation in it. They are an enhancment to the man page”Ick…INFO. I’ve never liked using those. Too much PITA. I happy with plain old man pages.I just wish that more man pages had an example sections. Some of them do, and I’m greatful that the authors included that. 2004-10-17 4:18 am and mostly important a “see also” section, fbsd man pages should be praised for that. almost all have a see alsothe same we cant apply for linux/gnu man pages 2004-10-17 4:32 am The other nice thing about the FreeBSD man pages is that they are *all* available online, going back to FreeBSD 1.0. They also have available the man pages for OpenBSD and NetBSD, as well as a few different Linux distros. Very nice. http://www.freebsd.org/cgi/man.cgiThe other nice thing about the FreeBSD Documentation Project is that everything they produce is included with every release of FreeBSD. If you install the docs package during the initial install, you get everything, including the Handbook and Porter’s Handbook, in /usr/share/doc. If you didn’t install the docs as part of the initial install, you can grab them using cvsup (there’s a sample docs supfile in /usr/share/examples/cvsup). Just be sure to set the DOCS_LANG variable in /etc/make.conf to the language you want, otherwise you’ll get every language available. There’s nothing like having all the documentation for the OS installed with the OS. Very handy for those times when you just can’t get the network to work and you can’t use Google.