Learning new technologies can be a double-edged sword. On the one hand, lots of free documentation is readily available on the internet. On the other hand, most of it is not written by writers, but by techies. Techies (like myself) tend to make terrible writers.
Right now I'm trying to deepen my knowledge of a programming language called Perl. There's tons of useless documentation on Perl.com. I say it's useless because it's not written very well. It's riddled with spelling mistakes. Spelling mistakes in technical documentation can be bad. The right kind of error in the right spot makes you ask the question "Wait...is that a typo, or does that word actually mean something special I don't know about?"
And you can't find the documentation from the home page. I had to find it by Googling something specific.
It's also not the most clear. I'd wager that it's written by programmers. Technical writing is a special talent. In order to be a good technical writer you need to be able to understand technical concepts. You, then, need to be able to communicate that to the masses in writing. And you need to make it simple and understandable.
I think programmers approach technical writing with certain assumptions of the reader's knowledge. A good writer makes no such assumptions, at least without stating the assumptions.
I find a great divide exists in technical writing. There are three broad levels of expertise. I'll call them "beginner", "intermediate", and "advanced." Documentation written for beginners is necessarily simple. It's aim to get the reader from knowing nothing on a subject to being functional.
Documentation for advanced people seeks to inform of things little known, or advanced tricks. It assumes intermediate knowledge. It assumes more than what basic documentation will give you. It intends to make you a guru.
Documentation for intermediates is to bridge the gap between beginner and advanced. It assumes you're familiar with beginner level concepts.
In my experience, very little intermediate documentation exists. I'm in the unfortunate position of being intermediate on many computer technologies. Books for Dummies and Complete Idiot's Guides don't do much much good. Many other books would require a lot of research effort just to read.
Where's the documentation for intermediate's like me?!
8 comments:
I learned PHP first, and syntactically they are very similar, then I used the O'Reilly perl in a nutshell book to learn a fair chunk of the API and functions, after that it was just reading documentation on individual libraries on cpan (Which I highly recommend as a quick reference for any Perl module), there was another O'Reilly book that I borrowed off a co-worker that was pretty good, but a lot of the documentation on Perl is of a very practical sort, I couldn't find a lot of stuff on specific design techniques with perl, but lots of implementation stuff like the Perl Cookbook was helpful
The documentation on CPAN is the stuff that sucks the hardest!
It's written in such a way that if you immediately understand it, good for you. Else {too bad.}
Maybe we're reading different CPAN documentation, but that which I have been exposed to gives a principal, but often does not give examples.
I want to see examples, with output.
The PHP manual is great! It's easy to search for what you're looking for. At the bottom of each page they have a comments section for people to say "Hey, I've found this extra bit of code useful." or "The explanation about such and such wasn't too clear. Think of it this way...."
I wouldn't object to getting a Perl book. Before buying a book I'd want to make sure it was worth the money. The last few times I've checked the Chapters in the Ottawa area, they only had Perl for Beginners, or something. It's not worth the money. That tutorial is on the interweb in about twenty eight million mirror sites.
Seriously, do you want to learn perl. Unless you have a specific reason to use perl, try python. The syntax is much saner IMHO. I guess Perl has a bigger set of contributed libraries, but I have never had problems with Python.
I am without choice here. Given preference, I'd do PHP, or Java.
But we use this software at work that runs on Perl. I need to write and rewrite some of the scripts it uses. So, I kinda have to learn more Perl.
Heh, As to Perl vs Python/Java/PHP, Some points against all of them, Python is whitespace delimetted, what the hell?, Java is pretty hefty, and PHP has had a LOT of serious security problems, not to mention it's pretty fugly naming conventions.
The cpan stuff is just an api reference, occasionally with examples, it's a good way to learn how to use given modules but not perl itself,
Perl is very mature, it's been around a long time, that means it's quite fast, has had most of the security bugs run out of it and is widely supported, (Moreso than python, probably less so than PHP, God only knows why though)
It also means you might be able to grab a perl book or two from the local library, thats where I found mine, sure they were like 8 years old, but they got me up to speed on the syntax and basic concepts which haven't changed in that time, as well as a lot of the common modules (Like DBI and CGI)
Perl as a language is fairly simple, it's strength is that it's mature, and that there are about a billion modules on cpan for it that can do anything you desire, (Some that I'd make sure you are familiar with, are DBI, HTML::Template and CGI, though you shouldn't really use CGI for anything but cookies and hostname stuff unless you like tearing your hair out), Once you are familiar with the language and those modules at least, you can dig about in stuff like the perl cookbook for specific tricks and cool stuff you can do, But I'm not really sure what area's you want to improve on, Perl is just another language though with features geared towards particular things (Text processing is usually the biggy, and it positively sings in that department),
I've never used Python, but Java is pretty hefty.
I have heard that PHP has security issues. I don't know what they are. It's really too bad. PHP is a nice language in which to work. Since it's open source, it has the potential to be fixed. I'm surprised it's not fixed yet.
Basic Perl is pretty simple. But I find OOP Perl gets a little more complicated, especially when passing method references around. Then I see stuff like this in the code:
/DIRECTORY_NAME/ and $Pkg::variable=value;
Wednesday Thursday Friday?! That looks to me like it returns a boolean value, but what's it returning to? That wasn't a part of a line. That was the whole line. And that line will appear twice in a row with only the DIRECTORY_NAME changing.
It doesn't look like it's doing anything. It looks like it could be a condition for a condition statement.
And how does one even look that up in a reference? Other than the slashes, the word "and", the "=" and the ";" everything in that is specific to my application.
Until now I haven't had to worry about packages and modules. So that's new to me too. So I haven't had to worry about HTML::Template, CGI, or DBI.
Mind you, my inability to understand the docs may be due to my perpetual insomnia. Coffee may make you more alert, but I'm not sure it sets your mind to the state it would be if you had sufficient sleep. (Stay tuned for my take on insomnia on November 19.)
hahaha ok, I actually had to get that lined explained to me by my local perl guru, apparently it's equal to (But much more obtuse than)
if ($_ =~ m/DIRECTORY_NAME/) then { $Pkg::variable=value; };
Thanks.
Post a Comment