Tools and standards for technical design document

Question

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?

Answer 1

Unless your projects are cookie cutter, then it only makes sense to apply the best combination of tools for the job at hand. That said, some loose (rough guidelines) or narrow (applied to specific circumstances) standards are probably warranted.

Answer 2

A thorough discussion between the lead developers or team members (possibly recorded for later) is much more valuable than any document, in my opinion. Give them all the freedom to choose their tools and ask them only to write a short summary of the high-level technical decisions early on. This can be the foundation of documentation later on in the project. A technical design document gets outdated too soon and takes too much time to write.

Answer 3

I think there should be one set of tools and standards that are specified at architecture time that describes how design should be documented. It's really important to have a standard for documenting these things; otherwise, they tend to fall by the wayside; and if the design documentation is heterogenous, there's a danger that the people who really need to know the most about the design may not be able to find the design information they really need when they really need it.

That said, the choice of tools and standards is entirely up to each different organization; whatever works for an organization is right for them. So long as there is consistency in the standards (and the tools, to some extent), whatever is chosen for an individual organization is right for them. It just needs to be decided upon, and enforced.

Answer 4

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.