My buddy used to say that "Documentation is the Power of Information". We have a ton of documentation that says how our system is supposed to work. In the good old days, all of this documentation was written with Adobe FrameMaker. When we published the docs, they were converted to PDF format. This worked pretty well. If you needed to make changes you did it in FrameMaker. Then you told the documentation team to cut a new PDF copy to release. A couple things happened on the way downhill. At first our documentation team got cut, leaving us with contract documentation support when needed. Now we don't have anybody. So we have to sacrifice one of our programmers to be the documentation guy.
Another thing that happened was we went to Rational Rose. This in and of itself is not a bad thing. The theory actually sounded quite good. Do all of your design in Rational Rose. Then run a report to extract the design info to Microsoft Word output. The problem is that this report process doesn't really work too well. So now when we need to get documentation updates, we make the change manually in the Microsoft Word file AND update the Rose source.
Something is very wrong with this process. It is no wonder I have little desire to add all the good design information to the design docs. Somewhere along the way to having the system fully documented in a nice tool like Rose, we got derailed into a documentation nightmare. So much for documentation being the power of information.
