RTFM

Ye' old general discussion board. Basically, for everything that isn't covered elsewhere. Come here to shoot the breeze, shoot your mouth off, or whatever suits your fancy.
This forum is not for asking programming related questions.

Moderator: General Moderators

User avatar
s.dot
Tranquility In Moderation
Posts: 5001
Joined: Sun Feb 06, 2005 7:18 pm
Location: Indiana

RTFM

Post by s.dot »

I have an issue to address with people reading the manual.

When I was new to programming, I'd ignore such requests to read the manual, because if I could get my code just 'working' then it was good, and I'd move on to the next problem. Thus, I'd search for someone to give me the answer or point me in the right direction.

Then by reading the manual to solve my problem, i soon realized that there were fewer and fewer 'next problems'. So that brings me to my point.

Why are so many people (including me a long time ago) reluctant to RTFM? Are they scared of the big words (i was a bit intimidated at first)? Are they lazy? Do they not have time? Or are they just looking for the quick route with someone telling them the answer?

I can't remember what my reasoning was.
Set Search Time - A google chrome extension. When you search only results from the past year (or set time period) are displayed. Helps tremendously when using new technologies to avoid outdated results.
User avatar
shiznatix
DevNet Master
Posts: 2745
Joined: Tue Dec 28, 2004 5:57 pm
Location: Tallinn, Estonia
Contact:

Post by shiznatix »

i = lazy
User avatar
JayBird
Admin
Posts: 4524
Joined: Wed Aug 13, 2003 7:02 am
Location: York, UK
Contact:

Post by JayBird »

i agree Image
matthijs
DevNet Master
Posts: 3360
Joined: Thu Oct 06, 2005 3:57 pm

Post by matthijs »

A long long time ago (not!) when I started with php the manual was just too complicated to read. The syntax alone would be intimidating. for example, looking at something like
int preg_match ( string pattern, string subject [, array &matches [, int flags [, int offset]]] )) was like "huh??"

Also, the sheer amount of possibilities can make it overwhelming. Was it str_replace, str_ireplace, strstr, strpos,strrstr, substr, etc etc?

And last, although the manual describes all functions very well, it's hard to find an answer to a "why and when". Someone who wants to do something, just wants to find the function that best solves his problem. Reading the complete manual to find what function that is, is quite some work and difficult.
timvw
DevNet Master
Posts: 4897
Joined: Mon Jan 19, 2004 11:11 pm
Location: Leuven, Belgium

Post by timvw »

As matthijs said, for an average beginner most manuals are way to hard to understand (certainly if they are in a foreign language). And don't even mention reading an RFC because these are way too confusing ;)

Anyway, after a while you reach a point where you can actually understand what is written in these manuals. And then you reach the point where you can read an RFC and understand what it's trying to explain ;) And after that you're ready to help writing the manual or become the manual ;)
Grim...
DevNet Resident
Posts: 1445
Joined: Tue May 18, 2004 5:32 am
Location: London, UK

Post by Grim... »

I never, never have a problem helping someone that wants guidance or advice.
What I really object to is someone who wants you to write their entire code for them.

That's why I'll say 'take a look at str_replace' rather than '$text = str_replace('bob', 'jane', $text)' - handing out the answers doens't help anyone learn.

<rant>
Also annoying: 'I've never used PHP before and I want to make Flickr2 (or something)'.
Walk first, for God's sake.
</rant>
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

Post by Maugrim_The_Reaper »

People think a simple interface equals a simple program in terms of source. Well, at least those of them new to programming to general do..
Roja
Tutorials Group
Posts: 2692
Joined: Sun Jan 04, 2004 10:30 pm

Re: RTFM

Post by Roja »

scottayy wrote:Why are so many people (including me a long time ago) reluctant to RTFM? Are they scared of the big words (i was a bit intimidated at first)? Are they lazy? Do they not have time? Or are they just looking for the quick route with someone telling them the answer?
I think you pretty much nailed all the answers.

I don't mind people who cannot understand the manual saying "I visited the manual page for blah(), but I really don't understand how to implement it". That is the vast minority, however.

Of course, you can't immediately be annoyed by everyone that asks and hasn't read the manual - anyone can have a lapse of memory, or a moment where they aren't thinking clearly.

But it does get annoying when people are more willing to spend the time to post a message asking an obvious RTM question than they are to open the manual. Some days I ignore those posts, other days I throw a quick link to the man page in question.
User avatar
feyd
Neighborhood Spidermoddy
Posts: 31559
Joined: Mon Mar 29, 2004 3:24 pm
Location: Bothell, Washington, USA

Post by feyd »

I'm a believer in documentation being a directed resource. In this case, the php manual is for a somewhat seasoned programmer, more or less used to function prototypes and declarations from other (more strongly typed) languages. So I can understand the feeling of overwhelming when reading the manual about a function for the first time. However, that's where helper/introduction pages come in. They can bring many people up to speed provided they are written well in a simple, yet informative, non-condescending manner. It's difficult to do for many writers of manuals but the effort does show.

Manuals that do put this effort into the documentation often become quite lengthy however. MSDN does a pretty good job, in my book, of documenting much of the functions in various APIs and SDKs and such. But the descriptions for any random function are often several pages worth (in print.) Daunting to some newcomers no doubt.
Grim...
DevNet Resident
Posts: 1445
Joined: Tue May 18, 2004 5:32 am
Location: London, UK

Post by Grim... »

Everyone can forget functions.

A bash quote springs to mind:
bash.org wrote:#12768[X]
<eltawater> anyone know the name of a (mathematical) function which calculates how many times a number M fits into a number N?
<eltawater> i.e. 20,4 = 5
<eltawater> ?
<Biddle> Division?
<AlleyCat> divisor
<eltawater> er
<eltawater> *smacks head into desk*
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Post by alex.barylski »

IMHO There is a difference between a manual and a Introductory book, etc...

A manual is (unless you have previous programming experience) more of an API reference for intermediate to advanced developers. Some manuals have full examples of how to use functions and some only have snippets to demonstrate how to use functions and others have no examples at all.

I tried learning Windows SDK development reading the Windows 32 programming API bible for Windows 95...granted there are some complete, enter->compile examples, most are only snippets...

That was the most frustrating experience, having only VBasic experience on Windows 3.1 and some knowledge of the underlying API.

The difference between C/C++ and Visual Basic is catastrophic.

Anyways, the point is, manuals aren't intended for complete newbies to begin learning a craft, they are more reference material for experienced developers.
User avatar
John Cartwright
Site Admin
Posts: 11470
Joined: Tue Dec 23, 2003 2:10 am
Location: Toronto
Contact:

Post by John Cartwright »

I want to also make note that you should always read the user comments. There are often some really insighment comments and suggestions that the manual itself does not provide.
User avatar
Benjamin
Site Administrator
Posts: 6935
Joined: Sun May 19, 2002 10:24 pm

Post by Benjamin »

My experience with the manual as a newbie was not so much understanding it, but rather finding the information I was looking for. I feel that the manual provided in the .CHM format is excellent for both newbies and experienced programmers because it has search & bookmark features. The only problem is that I can't use it in Linux :(
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Post by Christopher »

I think the problem with RTFM for newbies is that when you are starting out you usually are not even sure what the question is. A manual is for someone who know how a thing is organized. The PHP manual is for someone who understandis the general design and naming conventions of PHP and its libraries (and maybe that naming conventions and libraries even exist).

A while back I posted here a list of what I think should be required reading for newbies in the PHP manual. But if you notice the sections are all over the place in the manual. How would a newbie know that those are the basic knowledge sections in the manual?[/url]
(#10850)
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Post by alex.barylski »

Jcart wrote:I want to also make note that you should always read the user comments. There are often some really insighment comments and suggestions that the manual itself does not provide.
Very true :)
Post Reply