Menu
I would like to know what tools and standards are my colleagues using for technical design documents nowadays.
In the past when in my company we were only delivering client-server win-apps we had word templates for our design docs. Our templates always started with the Database diagram, then the UI mockups, field mappings, functionality description, etc... With Word and Visio we had enough. But lately we are combining Wikis, UML diagrams, prototyping tools, etc... With no really strong policy for standards and tools. Do you think is good to give architects the freedom to choose the set of tools and standards they find fit at a given moment per project or should the company enforce and standarize on this?
330
A Technical Design Document (TDD) is written by the development team and describes the minute detail of either the entire design or specific parts of it, such as: The signature of an interface, including all data types/structures required (input data types, output data types, exceptions)
Documentation Standard means the standard of quality and formatting of documents as stated in an Order. At a minimum all documentation created must meet or exceed applicable industry standards.
From my experience, there are seven essential parts of a technical spec: front matter, introduction, solutions, further considerations, success evaluation, work, deliberation, and end matter.
There are five major types of product technical documents; product manuals, user guides, repair manuals, API documentation, and SDK documentation.
Documentation standards in a software project are important because documents are the only tangible way of representing the software and the software process. Standardised documents have a consistent appearance, structure and quality, and should therefore be easier to read and understand.
The reason behind any design documentation is clear communication to all involved. So from that point of view, whatever tools you as an architect select, the finished product needs to be read both now by all involved, and later by maintainers. It therefore makes sense to select at least some fairly standard tools, that will still be around in a few years.
That said, design documents are generally used to get the project or system up and going. Thereafter well documented code, and some basic documentation should be sufficient. I would probably pay more attention to the organisation of your documentation, so that people can easily find what they are looking for in the future. It can help to enforce some kind of standard repository structure/system for storing documentation, but don't necessarily insist on all sorts of templates for documentation. Focus on the content and not the tools.
177
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
