It occurred to me in a project meeting today, that CRs and Spec docs create a grand pain in the arse to manage and implement. There are a few issues, firstly that it is very difficult to follow change and secondly these documents are often not updated.
Anyhow, I figure a text based solution using something like latex would be best, and unique amongst any project I have been on.
Of course, most people would need some training in writing basic documents this way. But I believe everybody should get training in all the tools and technologies the project deals with up front anyway - Most of the time these seem to be different, but if the projects maintain some stability then perhaps upfront training won’t be required as much as well.
This falls back on retention of staff, not only with a company, but a delivery team and that could be very difficult to manage. Some of these projects seem like people have been drawn out of a hat to serve time at the front before they can go home.
Update [29-Mar-2008]: The real message I’m trying to sell is that projects should have a management system that makes it easy to track changes; especially those implementing software technologies. I quite like Tex, though I haven’t really used it since University. A better technology might be XML - especially considering the ability to use XSL and XSL-FO to generate desired outputs; the abundance of XML editors that could be used create and edit the documents.
Some people might not like writing in XML (or TeX).
As far as I can Google, there is not a standard XML schema for the purpose of writing project documentation… perhaps that is something I can work on.
Once any text based document is used, it can be integrated with the rest of the system, including any documentation that is built from the source code. The significance of this is that the documentation can then follow the same processes that are applied to the application being built:
- defects can be recorded against a specific version of the documentation, if the documentation changes, all defects that link to that version of the document can be checked to ascertain whether they are still contrary to the design.
- changes can be linked to the version of the document that they apply, when changes are authorised, they can be implemented in the documentation and in the application source code or configuration.
- application source code documentation can directly reference changes that have effected implementation (if relevant).
It is my belief that application design, development, delivery and project administration is one process. A lack of organisation and process at one point directly flows through as information loss elsewhere. If a project is documented using word documents with versioning implemented using change history - it is completely incompatible with a development environment using a source control repository.
