| My best-in-class example of document management is Xilinx (now AMD). Internally, they use an XML flow based on DITA - but the specifics aren't nearly as important as an apparent organizational commitment to delivering quality documentation. (They hire technical writers - these job postings are how I've gleaned most of the details about their documentation toolflow.) In my small team, our solution has been: - Commit to PDF as a documentation mechanism. Trying to co-maintain HTML and paginated outputs is too challenging. - Maintain and track documentation in the same infrastructure as source code. For us, this means git and AsciiDoc (formerly, LaTeX). Asciidoctor to PDF via XSLT is crufty and slow but looks good enough and addresses most of our "wants" (table of contents, list of tables, list of figures, glossary, ...). - Try to keep documents consolidated in relatively few repositories. A project-wide repository allows documents to share content (e.g. images) and encourages a coherent, consistent document tree. - Provide a (hair-shirted, Makefile-based) mechanism to publish updated PDFs of these documents. Having a centralized publication site is critical, since it teaches people where to look and allows us to control document review/release cycles. Purpose-built documentation management systems (e.g. Alfresco) might seem be better tailored towards documentation and might play nicer with Word, but it also keeps documentation in a ghetto and allows people to abandon it. Less is more. |