Open Source

RTFM: I did, and it didn't help


It's almost a battle cry for the open source community. Before you go to mailing lists or forums for help, you are expected to RTFM (I think we all know what that acronym stands for right?) But there are situations where RTFMing simply doesn't help. Case in point: Packetfence.

Recently, I was asked by my editor to do an article on the open source NAC Packetfence. I jumped on the change to learn something new and cover it for TechRepublic. So I did some reading about what it was and set out to install the system. I RTFMed and thought, this sounds very do-able. Well the FM was simply off the mark. In fact, in my 10 years of dealing with Linux and open source, I had never come across an "FM" that was so lacking in the actual "how to" area.

So I had to do some research of my own. This research sent me digging through configuration files and googling -- you name it. Finally, I got the system set up and running.

And that covered an entire article.

But now - what do I do? I had an article that was over 2,000 words that only covered setting up the system. Looks like another piece was in store. So I then had to figure out how to use the system. Easier said than done. RTFMing once again didn't help. I could get certain aspects of the system working but no more. So I wrote about those certain aspects of the system.

Two weeks down trying to cover one piece of software. I knew there was more to come.

It was at the end of the third week I had a HUGE AH-HA moment and set out to write about using the system again. The AH-HA moment was right on and I got my third article (only to find out there was a fourth ready and waiting).

Oh, and in the middle of all of this, I had sent an e-mail to the creators of Packetfence only to NEVER hear back from them. I had told them I was a writer for TechRepublic covering their system. Nada.

So after all of  the time and energy I put into getting this system covered, I had to think about what so many of the open source community would say before they would offer one word of help.

RTFM

Well I did, and it offered me very little help.

I have to wonder: Why is it the open source community doesn't reach out to people like myself who do this sort of thing for a living? Oh wait, actually I have reached out to certain projects offering my help with documentation only to get snubbed. To their snubbery I want to say, "I have been translated in blah blah languages and published in blah blah blah and so on ad nauseum...." But I do not. I figure if they want my help (or the help of others like me), they'll seek it out.

Until then, the FMs will continue to be subpar how-tos that, in many cases, do not show us "how to."

This sort of ties into one of my last articles (on Guru'ing). There is a lot of help out there for Linux and open source. Some of that help will come from people who frequent this site. And I would like to think the wonderful people here (people who many of us have all grown to know and trust) would never say RTFM to someone obviously in need of help. So if you are ever looking for help with Linux or open source, and you hear the phrase RTFM, know that most likely that is either someone too lazy to type or help or someone wanting to make sure you understand exactly what kind of help you are looking for before you look.

Either way RTFM is just not right. In the open source community the FM IS the community in most instances. And when we reach out for help we ARE RingTFingM.

About

Jack Wallen is an award-winning writer for TechRepublic and Linux.com. He’s an avid promoter of open source and the voice of The Android Expert. For more news about Jack Wallen, visit his website getjackd.net.

28 comments
Jaqui
Jaqui

I agree with you on this Jack, most often the documentation sucks. I've spend months now learning about Apache modules for Apache 2, each one usually has the same problem, the manual sucks bo-bo . Even the "Definitive Guide to Apache 2"'s are next to useless for any detailed coverage. The source of the problem lies in that those heading the projects are developers, who have forgotten the end user's needs, and write for.. developers. The TLDP often gets completely overlooked by everyone, a group of people who are working on getting current FMs to R for all open source projects, even if those are the same as comes with the software. If people who knew a particularly usefull application well would write a good manual and submit it to the TLDP then they would have better quality manuals than what is being shipped with the software. The TLDP has guides to generate the format they prefer to use for the website available on the website. [ you know the howtos available for install from most distros? those are from the TLDP, as is the bash manual, Linux System Administrators Guide, Network Administrators Guide. [ SAG and NAG in the repos ] ] They run into the same problem as any other volunteer group though, people drop out and stop contributing, stop maintaining a document / manual / guide so it becomes outdated.

davidbteague
davidbteague

There is a Wiki. We should all add to that as we figure out how to do stuff. Generally, I find the user community essential for Windows and for the Mac, especially the Mac which is supposed to be so very "easy" to use. But I always Read The Fine Manual. FIRST!

Justin James
Justin James

I would say that 90% of the software out there (both open source and non-open source, free and commercial) has lousy documentation. Indeed, I usually start the *other* way around, making a list of well documented packages that I have used. The list is disgustingly short. It runs along the lines of: * Apache * MySQL * Perl * IIS * Anything .Net (that documentation seems to be getting worse, sadly) Try, for example, to make sense of the sed manpage. I stared at it for what seemed like ages trying to figure out how to use it, and I am an experienced regex writer. Or run xconf one day. Just try it. I have been around this industry since before puberty, and I did not know what to start looking to get the answers to some of the things I was asked, and the man pages ("man" stands for "manual", right?) was worse than useless. So yeah, when I am told to "RTFM", my response is usually, "GFY", because by the time I publically ask for help, I've already exhausted the manual and the search engines. And let me tell you, whoever said that the open source communities are these really nice people who love to help... they lied. My experience has been that for "easy" questions I either see "RTFM" or a link to a "duh" answer that is in the first 10 results on any search engine. Any hard question just sits there unanswered for years. J.Ja

david
david

Jack, I'm sorry you weren't pleased with your PacketFence support experience. To start, I feel it's important to disclose to your readers that "never", as used in your article, means "three business days". Admittedly, three days is a bit long to wait for a response. However, as our website makes clear, the PacketFence mailing list is the primary support venue. There are well over 100 subscribers willing to share their experience. As it was, the core development team was extremely busy last week. The single-point of contact issue is exactly what a support community is intended to address. I'm sorry you felt your support request was "special", but we try to treat our users identically. In regards to lacking documentation, and specifically "how to", I'm really at a loss. The PacketFence Wiki includes configuration guides, FAQs, and HOWTOs for RHEL, Fedora, SUSE, Ubuntu, Gentoo, and Debian distributions. We also offer the PF ZEN virtual appliance, which trivial to get up and running. Your article did not specify which release you chose - or even what problems you experienced - but I assume you did not try PF ZEN. Again, I apologize you didn't find the help you were looking for. In the future, I'd suggest you follow the proper support avenues to receive a timely response. best, David LaPorte

CharlieSpencer
CharlieSpencer

"The source of the problem lies in that those heading the projects are developers, who have forgotten the end user's needs, and write for.. developers." Two other thoughts on this comment. The original developer strikes me as the best source for information on their program. Developing programs is fun; documenting them isn't, especially if you aren't getting paid for it. If the developer is motivated enough to thoroughly document his / her product, he may not be a writer capable of explaining technical topics to a non-tech audience. Neither of these comments is meant to imply the documentation from proprietary products is automatically superior to that of open source. Having noted that, perhaps the paid-support distros aimed at the corporate market will begin writing FM's for the apps they include.

w2ktechman
w2ktechman

I usually exhaust web links first, especially if I am in a hurry.

ctucker
ctucker

I am a seasoned Windows user and very comfortable in setting up new boxes, loading the OS, configuring a server and small network, etc. However, I am brand new to Linux and am appalled at the lack of real support. But then I've been told, it free software right? True, maybe we should accept that you get what you pay for (or in this case do not) however to say that the linux community is supportive to anything but the most obviously is not necessarily a good analogy.

Justin James
Justin James

I just realized that this article was (partially) critical of the failure to receive an email from the *creators of some open source package*, not *a paid technical support team*. Personally, I am WEEKS behind on emails from family members and people I have known for decades. If a total stranger sent me an email asking for a long, thoughtful, step-by-step set of directions to making toast, I would ignore it for a few weeks simply because I am totally swamped. I am sure that David and the rest of the folks there are busy coding away, unpaid I may add, on this product in what time they do not spend at day jobs orf with their families. I would even bet that you have made more money writing *about* PacketFence than they made *writing* PacketFence. David, keep up the good work. Jack, please try to be a bit more understanding before slamming people or groups. I note that nowhere in your article is it mentioned that David or anyone else on his team or even the mailing lists told you "RTFM". In fact, the existence of a manual is a cut above typical open source experience. I wrote a lot more than 2,000 words trying to get MRTG up and running... J.Ja

rclark
rclark

We really, really need a YODA (starwars type, not an achronym) instead of a manual. It never ceases to amaze me how people who have a bright idea and create a systems expect the rest of us to be experts at their particular brand of insanity. We do it to our users too, but geeze, we expect more from our peers.

Tony Hopkinson
Tony Hopkinson

M*nu*l. Your mum needs to wash your mouth out with some soap. Disgusting.

CharlieSpencer
CharlieSpencer

We rarely hear from a software vendor in response to a TR column, discussion, or web log post. I don't know squat about your product, but it's refreshing to see a product representative reach out to the user community in a public forum, using his own name and not an alias.

jlwallen
jlwallen

for one thing there should be made some very obvious details about the differences between the types of systems that the configurator.pl will set up. also - the installations are based on old distributions. Fedora 4??? Fedora 8 was just released. I attempted to install on Fedora 6, Fedora 7, Ubuntu 10, but finally had to install on Ubuntu Server 6.06. Now I sent the email to the Packetfence group over a week ago. That should have been plenty of time to get some sort of response. Now don't get me wrong - the product is FANTASTIC!!! In fact I would go so far as to say it is one of the most impressive products I've seen in a long, long time. I did not try the Zen because I was writing articles based on production environments. The release I was using was the most recent from the website.

davidbteague
davidbteague

Read The F**king Manual and Read The Fine Manual have both been meanings for RTFM since I have been in computing. I started in 1957, with an IBM 650 "minicomputer", coding in SOAP and FORTRANSIT, long before there was a "man page" for anything. Where have you been that you have not heard "Read The Fine Manual"?

OnTheRopes
OnTheRopes

Nobody can be offended ever! Whassamatter you?

CharlieSpencer
CharlieSpencer

We're a limited gene pool, but those Linux experts we have here are very helpful. Just be sure to post your query as a "Question" and not as a "Discussion". One of the problems I've encountered is people who are trying to be helpful but are mistakenly changing the subject. I've seen this most often in responses like, "I know how to fix this in SumUdderDistro; why don't you install it instead of DistroYouAxedBout?" The most useful advice I can offer regarding Linux web assistance is to ignore the meaningless responses. Ignore the "RTFM", "Change distro", and "Change application" responses. If the response doesn't answer your question, don't get into a debate with the responder. If you don't get a useful answer in 24 - 48 hours (depending on the overall activity on the site, weekends, etc.), post an update or two to your original post so it will move back to the top of the site.

Justin James
Justin James

... that paid-for help typically is not any better. But they *have* to try to help me, at the very least. :) J.Ja

CharlieSpencer
CharlieSpencer

J. Ja., there's a difference between letting messages from family and friends lounge around in your personal box, and treating support messages the same way. Jack doesn't say, but I would hope PacketFence has a separate addresses and mailboxes for support and non-support messages.

jlwallen
jlwallen

the email was made very clear that i was covering the technology (writing documentation basically) for techrepublic. i would think that would make the correspondence a bit different than just a "help me, i can't get it running" request. not only was the application getting media coverage, it was getting a helping hand by having in-depth documentation written for it.

david
david

Thanks very much for the compliment! It is true that the tutorials are for slightly dated OSes, but the all-in-one nature of PF ZEN and the PacketFence installer don't lend themselves to being at the cutting edge. If you're still interested in getting PacketFence up and running, we'd be happy to help. I would ask that you start with a post to our mailing list. thanks, Dave

Tony Hopkinson
Tony Hopkinson

We are not exactly PC up here. If some one did say Read The Fine Manual we would assume he was taking the FP. :D

jlwallen
jlwallen

i am trying to come up with a recursive acronym for this situation. READ: Read Every Attached Document ?????

OnTheRopes
OnTheRopes

But then I've always lived on the wrong side of the tracks. We don't talk like that over here. We ain't cultured like you un's. Thanks for larnin' me.

w2ktechman
w2ktechman

but then again, all acronyms are taught to us, and if I have only been taght that the F stood for something else, then that is the only word I had associated with it..

Penguin_me
Penguin_me

Also another good place to get some decent help are the various LUG's (Linux User groups) around the world, you sign up to the mailing list and then ask your question. In my experience they are always willing to help, and usually respond pretty quickly with useful information. I've never had a RTFM from a LUG.

Jaqui
Jaqui

Specially Charles who is new to linux, probably the best place for questions where you get a real answer is linuxquestions.org I won't say you won't see any RTFM responses, but those are far fewer than other venues of support. [ you will see stress junkie answering linux questions there much more than see him here. :) ]

Justin James
Justin James

I agree 100%. And in the case of supporting an open source package, I would probably (hopefully!) put that support mailbox well below friends and family on many (if not most) days. :) J.Ja

Justin James
Justin James

It is quite possible he didn't read it, or even look at the subject line. It is possible that the spam filter picked it up. Or, something also quite possible, is that unless you have a CNet/TechRepublic account, he thought you were just name dropping to get quick assistance. My point is simply that regardless of the contents of your email, or who you are, or what you are, you still have zero reason to expect or demand a speedy response to a request sent to an email box that no one gets paid to read. Heck, let's look at it another way. What percentage of the reader responses to blogs on TechRepublic get a response from the author (where one is warranted)? Let alone within 3 business days? J.Ja

jlwallen
jlwallen

it took me a while but you have to remember i was looking at it from the perspective that i had to be able to document the installation and usage such that the readers could follow easily. my next article will be on using the Web-based admin tool.

Editor's Picks