Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask
 
PerlMonks  

(redmist) RE: The sad state of Perl documentation

by redmist (Deacon)
on Sep 14, 2000 at 22:43 UTC ( #32525=note: print w/ replies, xml ) Need Help??


in reply to The sad state of Perl documentation

"So Perl started out on UNIX, maybe it's time to loosen the ties?"

For the love of all that is good and wholesome, no! Under a *nix, developing Perl (and pretty much anything else) is soooooo much easier and better than under Windows. I am not trying to be a bigot (although I am probably being one anyway), but under *nix you have a real Command Line Interface in which you can use utilities like man, grep, tail, and perldoc to accomplish what you need to do in a more efficient manner. Plus you have multiple terminals (which you could have in Windows, but it would hog the task bar and screen in addition to the fact that it would be more difficult to keep track of the content on each terminal).

It's not really *one* thing or another, but many little things that make *nix a better platform to develop on than Windows.

Perl's association with UNIX is important because some of the functionality and use of utilities in *nix has carried over into perl itself. Grep (and regular expressions) for example. In addition to this, Perl culture has been influenced by *nix culture enough that it is important that we not forget our roots. There is no reason why Perl should become more disassociated from UNIX.

As for the quality of the docs, I think that the majority of the docs are fine as far as quality is concerned. Some are a bit misleading or are not as clear as I would like, but that's the nature of the beast. With as much documentation as Perl has, you cannot expect it to be perfect.

On the format issue, I don't know why you are so attached to the pdf format. If you want to print out some docs, nothing is stopping you. If you want docs with links, then docs are also available in html form. I don't understand why this is such a big issue for you.

Cheers, redmist
redmist.dyndns.org
email::redmist


Comment on (redmist) RE: The sad state of Perl documentation
RE: (redmist) RE: The sad state of Perl documentation
by Ozymandias (Hermit) on Sep 14, 2000 at 23:03 UTC
    Actually, red, I gotta disagree with you. I feel, and I know many others do as well, that UNIX is NOT a good development platform. Sure, you have this powerful Command Line Interface - so what? Humans do not work that way. The reason the GUI was considered such a huge advance is because it WAS. Even the ability to open four small term windows, each a complete CLI, and see all of them at once is a huge advantage. Add things like inline spell-checking, good Copy/Paste systems, and an interface that automates as much as possible, and you make for an interface that makes almost ANYTHING more efficient than it is with a CLI, including writing code. CLI is powerful, yes, but it's not perfect. It's a hammer, and a good one, but sometimes you need a scalpel.

    As it happens, I think the documentation that comes with the core of Perl is pretty good. On the other hand, I *DO* think Perl should dissociate itself from Unix. Why? Because Perl is a tool. It's a great tool, as perfect for its purpose as any - but its purpose is to make live easier for systems admins and web developers. And despite what the hype would have you believe, the internet is NOT UNIX. It never will be. The internet is ANY operating system. Perl should be, too. Take with it what we like about Unix, certainly. But just because Unix was the cradle of Perl doesn't mean Perl should stay there. You can't live in the cradle forever.

    - email Ozymandias
      OK, message recieved, zero distortion...I still disagree with you though.

      "that UNIX is NOT a good development platform. Sure, you have this powerful Command Line Interface - so what? Humans do not work that way."

      I don't think that your point about CLI and humans not working in the same way is valid. Why? Because computers and humans don't work in the same way. But it's ok this way. I have to adapt to the machine, because it won't adapt to me (at least until really, really good AI comes along). Even if the machine *could* adapt to me, I don't think that I would want it that way. I have learned to work with CLI, and have come to love it.

      One of the reasons why I think that CLI can be so great is that the rules are clearly defined (not intuitively, but through documentation) and both you and the SW that you are interacting with "knows" that you are two seperate entities, with different ways of working. In this type of environment, the SW or interface will not try to anticipate what you want or how you want to do something. Anticipation of human action usually results in it doing the opposite of what it's original purpose was: to help you and make you more efficient.

      Once you have adapted yourself to the CLI (or another non-human-anticipating interface), you can reap the results of such an interface.

      "And despite what the hype would have you believe, the internet is NOT UNIX. It never will be. The internet is ANY operating system. Perl should be, too."

      I don't want Perl to be tied to UNIX in such a way that would inhibit or diminish it's use on other platforms either. I just think that is important to keep the ties to UNIX that are already there. We should *transcend* the cradle.

      I realize that the Internet is not UNIX, but a damn big part of it is...and UNIX is also a big part of other networks and computing as a whole.

      redmist
      redmist.dyndns.org
      email::redmist
        Because computers and humans don't work in the same way.

        Escellent point. Computers and humans don't currently work the same way. But a GUI is closer than the CLI. And the next big thing (coming soon to a K-Mart near you) is likely to be something like an audio/visual interface - even closer to human-style interaction. It's not so unlikely that in 20 years or so, the neural interface will be the standard; and then computers WILL work like humans do.

        The point is that computers are tools too. Hammers started out as rocks slightly bigger than the rock you hit with it, which was infinitly more powerful than beating on the rock with your fist. That didn't mean the rock was perfect. People adapted to it, sure, but the rock changed. A wooden handle was added. The rock was replaced with bronze, and later, iron. Still later, the iron was replaced with steel. Now the wooden handle is being replaced with carbon and fiberglass and composites, and the shape is changing to fit the stroke of the human hand. Do you want to go back to the rock?

        One of the reasons why I think that CLI can be so great is that the rules are clearly defined (not intuitively, but through documentation) and both you and the SW that you are interacting with "knows" that you are two seperate entities, with different ways of working. In this type of environment, the SW or interface will not try to anticipate what you want or how you want to do something. Anticipation of human action usually results in it doing the opposite of what it's original purpose was: to help you and make you more efficient.

        This is true, but it's also not. <G> I hate the "predictive" things as much as anyone else, for the same reason - when it's right, it's great, but when it's wrong, it can be more stubborn than a three year old about changing.

        But that does not mean the interface is not better. Simple things like the dictionary in Word, as an example. (Not Auto-Correct. The dictionary.) A simple visual flag under those words that the dictionary doesn't recognize. It doesn't change them. It just notifies you that there's a problem, and if you know it to be correct, just a push of the button - and the dictionary now knows that word and will never flag it again. You can't do that on a CLI.

        On a GUI I can open two terms, on different machines, and see them both simultaneously. I can watch logs in real time while hitting a web server to see what triggers an error - and I still have the power of the command line to go back and manipulate the logs, as well. I know the command line well; I agree that it has a simplicity and a power that is not easy to beat. In fact, there's only one way to beat it - to assimilate it. Take the things that make it great and incorporate those things into something better. Like a GUI with Term windows; all the power of the CLI with all the flexibiity of the GUI.

        I don't want Perl to be tied to UNIX in such a way that would inhibit or diminish it's use on other platforms either. I just think that is important to keep the ties to UNIX that are already there. We should *transcend* the cradle.

        That would be fine, but it's more than that. Perl also needs to incorporate the lessons to be learned from Windows and VMS and shudder Mac OS. Believe it or not, not everything in Windows is crap. Not everything in Mac OS is crap. And the good bits weren't all stolen from Unix, either.

        I realize that the Internet is not UNIX, but a damn big part of it is...and UNIX is also a big part of other networks and computing as a whole.

        That's a fallacy that many people fall into, because it's such a good, clean, simple idea. Sadly, it's not true. Unix makes up a good majority of internet servers, true. But there's a sizeable minority of other OS's, including some Mac and NT/Windows 2000. And on top of that, in terms of CLIENTS, it's not even close. The sort of site you or I might run would probably average a high percentage of Unix clients, but as a whole it's a very Windows-ish world for client computers. As for "other networks" - hate to break it to you, but Unix doesn't rule the roost there, either. Netware and Windows make up an awful lot of business and home networks. Not that Unix isn't a part of it; Unix is a very important part of networking. It's a great OS for it. But Windows has learned how to do it now, too, and Netware always did have a pretty good idea.

        - email Ozymandias
      PerlMonks isn't the place for OS wars, but I have a few slightly on-topic comments:

      Actually, red, I gotta disagree with you. I feel, and I know many others do as well, that UNIX is NOT a good development platform.

      I disagree with you.

      powerful Command Line Interface

      Unix != CLI. The Unix (and really I'm talking about all the Unix spinoffs and clones here) philosophy has to do with operating system structure, and nothing to do with GUI vs CLI.

      I run Linux, running X windows, and Keep 10-12 xterm (CLI) windows open. The GUI allows this. This is not different than Windows or Macintosh in any way. However I have more tools (Thanks to GNU) available, I have compilers available (Does Windows ship with a C compiler?), etc. ActiveState has to do a fair amount of work for their Windows version of Perl, whereas the conversion to BSD or Linux or other Unix-like systems is far easier.

      Windows and Mac restrict access and reduce flexibility. That is why they are a poor development environment, and why Perl stays "in it's cradle".

      The reason the GUI was considered such a huge advance is because it WAS.

      Absolutely. And it was a huge advance YEARS before Windows was ever thought of. But it isn't a replacement, it's an extension. Some tasks are very difficult to do in a CLI, while others are very difficult to do in a GUI.

      Perl is a tool. Perl is flexible. It is and should be system independant.

        This *isn't* an OS war, and I never said the UNIX = CLI...all I was saying is that UNIX has a better CLI than other OSs. It was just an opinion, not an attack.

        "Windows and Mac restrict access and reduce flexibility."

        Definitely! That is one of the things I was trying to say using *nix's CLI as an example.

        redmist
        redmist.dyndns.org
        email::redmist

      Sure, you have this powerful Command Line Interface - so what? Humans do not work that way.

      /me is surprised to learn that he is not human.

      I hate to reach for the mouse because is not well designed for use by humans. It was apparently a design stolen from the race in "The Mote in God's Eye". I'm a programmer so I have to actually type quite a bit and I really prefer to do it fast so I actually use two hands for it. Everytime I have to reach for the mouse (and it usually amazes people how infrequently I'm forced to) I have to take one hand away from the keyboard. I hate that and it slows me down.

      The great advantage to the GUI is that it makes the learning curve more shallow. This is lovely for things that you've never done before or things that you only rarely do. For things that you do all of the time and that you are supposed to be an expert at, a GUI almost always gets in the way and slows things down. On the other hand, I like climbing steep curves so I'm probably a freek as well as being from another planet (certainly many of my cow orkers don't bother to become "experts" at editting, to my eye). On the gripping hand, there is more than one way to do user interfaces (TIMTOWTDUI) and no one way is the best for all situations.

              - All in fun, Love Tye
        I agree that every interface has its uses, and that includes the CLI. I didn't mean to imply that the CLI was in some way "bad".

        The GUI is nice not because it flattens the learning curve - it's still a pain to teach someone all the ins and outs of Word or WordPerfect, just as it was in the old CLI versions - but because it's a very nice Least Common Denominator. You can put the tools of the CLI on the GUI, and you can have your other tools at the same time - and it's up to you how you want them to look.

        - email Ozymandias
        I agree. I nearly choked when I saw that remark about CLIs and not human. But you said it much better. Let me paraphrase, and see if it fits.

        GUIs are fine for some people who need handholding for infrequent tasks or initial exposure. But CLIs give the advantage of fewer hand movements, and (most important for power users) the ability to script common actions or have programs drive other programs.

        One of the most frustrating thing about the Mac for me is that I can't really script anything. Sure, OneClick helps, and AppleScript can trap some of the interesting things, but I really can't tell anything "move the mouse to the topmost file that begins with F, and click there". That's too tricky.

        So what we really need is both. GUIs to help the casual or beginning user, and CLIs for the frequent or power user.

        Let's also consider one other factor in HCI design. I personally have a brain wiring that makes icons nearly useless, and I understand about 10% of the population are like me. I have to stare at each icon individually and name it, so that the next time I come to that icon, I can recall the name, and then access the meaning of the icon. If you simply present me with a dozen icons or so, I must tediously go through and determine the word for each icon. Thank the maker for tooltips... I just wish they would come up faster!

        If a tool has a way of turning all the icons off, I usually do that, or if it has a way of replacing all the icons with words, I even prefer that. So for the 1 of 10 people in the population like me, please, please, please give words near the icons, or provide tooltips. Otherwise, I will swear at you every time I have to use your program.

        -- Randal L. Schwartz, Perl hacker

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://32525]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others contemplating the Monastery: (10)
As of 2014-08-28 07:21 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The best computer themed movie is:











    Results (257 votes), past polls