Slash Boxes
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

cwest (1514)

  (email not shown publicly)
AOL IM: caseyrwest (Add Buddy, Send Message)

Perl geek.

Journal of cwest (1514)

Tuesday April 15, 2003
01:00 PM

Explicit Documentation

[ #11664 ]

I'd like to rant about assumptions made when documenting large systems. I'm glad I feel this way, because hopefully it will transfer into good docs for poest.

OpenSRS has some documentation. The problem is that it's horrible. It implies meaning and rules everywhere. The assumption that an unexplained example will tell me all I need to know about how to do something is rediculous. There is no way, in a single example, to tell me what I can and cannot do, you can only tell me one thing I can do.

I had written code that returned success from OpenSRS, only for me to find out that there was no success at all. That I was not conforming, but the documentation didn't tell me that what I wanted wasn't allowed. And it didn't tell me that the example was the only way.

I am mentally exhausted from trying to debug my code from response codes and failures. It's guess work. Sure, I like a challenge, I like the investigative process, but I don't like it when it is for (buzzword alert) mission critical application environments.

I'm tired now, and must sit on the porch in the amazing summer-like weather and vegitate.

Posted from, comment here.