Posts
295
Comments
27
Trackbacks
206
Documentation Sucks
I've spent the last day or so looking into web services and security, a topic I've managed to avoid for quite a while. I've done lots of reading, which has left me less thaan clear on my options, and have now started on WSE 3.0. Sadly the documentation here is also poor - lots of half-hearted bits in the documentation for the toolkit, but very little in the way of practical usage. The samples themselves aren't simple enough to give a beginner in this a good understanding of what to do to just achieve the basics, such as securing a web server. My current error is "The security token could not be authenticated or authorized", which is better than the ones I've been getting. The docs have a nice table depicting errors messages, the cause, and the remedy. For this particular error, the remedy is "Investigate the source of the problem". Useful that. How niaive I was in thinking that investigating the problem I could turn to the documentation.
[Listening to: Symphony No. 9 in D minor ('Choral') Op. 125: 5. Recitative - Allegro assai - Karajan - Symphonies Disc 6]
posted on Thursday, February 02, 2006 2:53 PM Print
Comments
# re: Documentation Sucks
Aaron Seet (icelava)
2/3/2006 2:05 PM
Hey Dave, this actually brings up a fairly interesting (at least to me) issue.

If product/technical documentation in its original form is splendid - thoroughly comprehensive, information, and _easy_ to read - would there ever be a need for technical books? :-)

Actually i know that answer to that one, since product documentation per se cannot cover a wide variety of other technical topics (e.g. design patterns). But i still ask the question.

Product documentation, especially for those of the most complex systems, are usually so poor I wonder sometimes if that is a deliberate move so that technical publishers can have an industry to thrive in. The quality of writing between technical documentation and that of established authors is way too great a difference. I then also wonder why companies don't directly hire authors to write documentation in the first place. Without any experience to know this for sure, I figure such a proposition would place heck a lot more working constraints on everybody than the current publisher business model does. Thus nobody actually wants to do this.

And it is with that where I draw the most respect for you authors - who take the half-baked documentation, try things out and make sense of it, then _translate_ into a form much more easier for the rest of us to digest and understand. It continues to amaze me how you guys can stomach it day in day out.
# Documentation Sucks (continued)
writerus drivelus
2/3/2006 2:30 PM
# re: Documentation Sucks
数据恢复
3/12/2006 1:40 PM
http://www.fixdisk.net
# re: Documentation Sucks
Michael Primeaux (iDynamics)
3/16/2006 11:59 PM
Have you resolved the error related to "The security token could not be authenticated or authorized". If I don't solve it soon the machine will die. Sigh.

Comments have been closed on this topic.