Here, have a blog entry on technical documentation
Steve Losh presents one here.
Among other things, he suggests that "Read the source!" and "Use the tests!" are useful adjuncts for people who know how the product is already built and generally works, but are not technical documentation.
What a concept.
But really, I was drawn in by this quotation, presented on the quotation of the day list that I subscribe to:
Wikis are an abomination. They are the worst form of "documentation".
First of all: assuming they work as intended, they have no coherent voice.
Have you ever taken a class with multiple teachers at once? Probably not, because it doesn't work very well (with exceptions for things like partnered dancing where there are distinct lead/follow parts).
Worse still: have you ever taken a class where there's one jackass in the room who keeps constantly raising his hand and offering his own (often incorrect) opinions? Wikis are like that, except they actively encourage random people to interrupt the teacher with their own interjections.
Posted on DreamWidth at http://doc-lemming.dreamwidth.org/148509.html. Try this link to reply over there.
Among other things, he suggests that "Read the source!" and "Use the tests!" are useful adjuncts for people who know how the product is already built and generally works, but are not technical documentation.
What a concept.
But really, I was drawn in by this quotation, presented on the quotation of the day list that I subscribe to:
Wikis are an abomination. They are the worst form of "documentation".
First of all: assuming they work as intended, they have no coherent voice.
Have you ever taken a class with multiple teachers at once? Probably not, because it doesn't work very well (with exceptions for things like partnered dancing where there are distinct lead/follow parts).
Worse still: have you ever taken a class where there's one jackass in the room who keeps constantly raising his hand and offering his own (often incorrect) opinions? Wikis are like that, except they actively encourage random people to interrupt the teacher with their own interjections.
Posted on DreamWidth at http://doc-lemming.dreamwidth.org/148509.html. Try this link to reply over there.