Documentation, the thing most agree is a good idea, but nobody wants to do. It's a nuanced subject. TOOLS Until recently, we used a combination of Documentum

Documentation, the thing most agree is a good idea, but nobody wants to do. It's a nuanced subject. TOOLS Until recently, we used a combination of Documentum and EPM (Enterprise Project Manager). The intended workflow was to have all documents start in EPM as part of the initial project implementing/building whatever product. When the project closed then the developer was to copy the documents across to Documentum. It was simple in concept. Due to technical shortcomings, it was not. I stopped even trying around 3-4 years ago. Documentum was a technical horror show. Ten years ago, and for a long time afterward, it supported only one browser, I believe IE. Architecturally, it seemed to use a Java applet for login and, upon successful login, it downloaded an app. Of course, the app wanted a specific version of the JRE locally. But, the real nightmare was authorization. One day you had permissions to update “cabinets” for your documentation. The next day you didn’t. No explanation. EPM had authorization issues similar to Documentum’s with the added bonus of a project’s link not working all the time. One day you could use the link, which the PM sent out at the start of a project, to access the project workspace. The next day you couldn’t find the project workspace. Currently, we're moving into a SharePoint site that is more promising. It provides Wiki capability for quick reference items, as well as, a repo for more involved documentation. Apparently, it provides versioning, but we haven't explored it yet. TYPES Part of the problem with the subject of documentation is that different groups want different types of documentation. Somehow, the developer is supposed to understand the needs of each group and produce a document tailored to those needs. Operational people want information on jobs and job dependencies. Support people want lists of things to check and try in case errors occur. (Developers are inherently bad at documentation for customer support. The problem is that we know how the system is supposed to work, so we’re blind to its shortcomings until a user finds them. Rather than my writing a support document upfront, I prefer meeting support people periodically so they can ask questions and develop their own document.) Management wants everything, all at once. They want it in the amount they want it, summarized, but detailed enough that they can feel like they’re a help during outages and architectural meetings alike. Users want to know every step for every task they need to accomplish, as well as, what to do in any anomaly, like not paying attention to dialog boxes and hitting “Save” to commit information that they didn’t want to commit. ISSUES The major issues, for me, are keeping documentation current and writing for such varied audiences, nevermind having the storage system working against me.