Sometimes closed circles aren’t funny. Just last night I was reading about the DRY (Don’t Repeat Yourself) principle in a book I recently picked up, The Pragmatic Programmer, Chapter 2. All good programmers with a bit of experience understand the need for a single point of reference for knowledge. Start sprinkling your code with literals or perform the same calculations in multiple functions and you’re wasting time, effort and making your code a maintenance nightmare.
What I hadn’t thought of though was time spent duplicating documentation of code. The pragmatic programmer would say, as many agile programmers also assert, that you document your code through the sparse use of comments and by writing clear, easy-to-understand code in the first place. What this means, and i’d never considered, is that writing a documentation document, a manual explaining your code and libraries, would the count as duplication of documentation.
The moral of this is to use something like NDoc for generating documentation, rather than relying on developers to update their docs. Why? BECAUSE THEY DONT DO IT! Thats why.
I just spent hours trying to figure out how to get this compiled trim addin to work – and it still doesn’t. First I was looking for the RegAsm.exe file they claimed was in the Trim Binary directory (it was in the .Net director), then I was looking for the external settings tab (doesn’t exist where it is supposed to) and now it still wont work so i’ve likely gone wrong somewhere in those last two steps.
The API support line has tried to be helpful, but have so far been ineffectual and the SDK documentation that shipped with the product is a joke.
Don’t let this happen to your product. Documentation is important. Documentation lowered the chance of have a grumpy prick like me yelling at you. Thats always a good thing. (Amount lowered declines as chance approaches zero – the limit graph of grumpy.)