Category Archives: documentation
Security by Cookery
Brief thread on apache user support list highlights Doing It Wrong:
Q1: How do I return 404 (not there) instead of 403 (forbidden) for my /cgi-bin/? IBM Rational AppScan utility tells me to. I tried […] but it didn’t work, and it blocked my application.
A1: I think you’re misreading your AppScan. It’s warning about potentially exposing filesystem information. But there’s nothing secret about a directory containing a web-facing application! Having said that, [read this doc for one way to do it].
Q2: That may be the case but their recommendation is still: Issue a “404 – Not Found” response status code for a forbidden resource, or remove it completely.
A2: Either they’re wrong or you’re misreading. But I can see what’s happening. It’s “chinese whispers”, starting from the CIS benchmark. Most likely someone along the way (IBM’s tech writer’s boss or somesuch) insisted that a meaningful explanation would be too difficult for their lusers, and either didn’t understand or didn’t care that it’s misleading.
Reminds me of some long and difficult arguments I’ve had over documentation in the past:
Me: (documents something non-trivial)
IdiotManager: You can’t say that, it’s too difficult
Me: I’ve put a lot of time&effort into this. I can’t see how to simplify further without misleading the reader.
IdiotManager: [suggests a token change that makes no difference to complexity]
Me: NO, THAT’S DOWNRIGHT WRONG!
IdiotManager can’t/won’t back down, and we end up with something like … well, I guess like the “security by cookery” document our questioner in the above thread was following.
Fortunately when I came to write a book, the publisher was more professional about these things. The editors would suggest changes, but never forced destructive changes on me. That was on balance a positive process: commonly an editor’s suggestion would lead me to rethink and improve how I expressed something.
This, I suspect, is a major reason why corporate documentation is generally so very much worse than either books or free software documentation.
The Documentation Gap
Quim Gil makes some pertinent observations on the documentation gap. He’s attracted quite a few comments, including one from me. Since commenting there, I’ve thunk further thoughts on the issue.
Firstly his points: there’s a shortage of people documenting gnome, and (he supposes) free software in general. But there’s no shortage of translators, nor of techies writing – the latter in the context of blogs. My response: documentation is a much more demanding task than translation or blogging.
But there’s still more to it. When you document a project, you study it in detail, you see what’s wrong. If you have the hacker mentality, you want to go and fix it before documenting something that’s not right. That applies mostly at the top end of documentation, where accuracy and thoroughness are expected.
Another observation: Commercial software shows a different face of the same problem. Documentation exists, because someone is forced (and paid) to write it. The first iteration isn’t (necessarily) so bad, but then some pointy-haired middle-manager insists on a bunch of changes that distort it out of all recognition. The end-result: documentation written to process, that is utterly useless and bears little resemblance to reality. I struggled last year with Oracle’s truly appalling documentation, and my blood pressure rises every time I have to try and use Microsoft’s.
I won’t get started on documentation-by-committee, that affects organisations such as the W3C. Not today, anyway.
niq's soapbox 