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 caseywest.com, comment here.
