| I have come to believe that tools will never solve philosophy-of-use problems. This solution may not scale, but I am confident that a team of 5-10 technical writer/archivists/internal consultants under the command of an extremely rigorous leader could handle widespread documentation for a company of 100-200 people just by using a LaTeX/Git/Wiki stack. This is related to problematic changes in the field of requirements management. A few decades ago, various companies invented technical requirement databases for large-scale engineering projects, and moved their document-based teams onto these new databases (DOORS, etc.) Engineering managers think it's like this: Databases (good) > Documents (bad), and they get paid by the metric. And that's the good managers. The bad managers hate changing anything and want to stay with documents. This, unfortunately, is a reduction of the problem. Most requirements teams didn't have a robust architecture for writing and storing requirements even in their document-based method. The actual hierarchy goes like this: Database with excellent plan (best) > Documents with excellent plan (good) > Database with no plan (bad) > Documents with no plan (worst). Most legacy requirements engineering teams have no idea just how bad the situation is, and have no desire to improve their consistency or internal organization. This attempt to replace documents with databases seems to be analogous for the modern software company attempt to shift from hard docs to widely-accessible wiki-style docs, or at least it certainly is at the pure software company I work for now (I came from more tangible engineering). Rules for storing documentation are almost more important than the documentation itself. My current team generates documentation at a very large rate; it's completely unsynchronized, the articles vary stylistically and structurally, the linking is inconsistent, and labelling is nonexistent across divisions. We need a hierarchical documentation structure imposed on us tyrants, consulted by the company-specific subject-matter experts. It's like comedy--much easier to write a sketch about broccoli than it is to write a sketch about anything. |