Tools and standards for technical design document

Question

I would like to know what tools and standards my colleagues use for the technical documents of the project at the moment.

In the past, when we only delivered client-server win-applications in my company, we had text templates for our project documents. Our templates always started with a database diagram, then UI layouts, field mappings, function descriptions, etc. With Word and Visio, we had enough. But lately, we have been combining Wikis, UML diagrams, prototyping tools, etc. .... Without a real policy for standards and tools. In your opinion, is it good to give architects the freedom to choose the set of tools and standards that they consider appropriate at the moment for each project, or if the company will ensure compliance and standardization of this?

Answer 1

The reason for any design documentation is a clear connection with all participants. Thus, from this point of view, no matter what tools you choose as an architect, the finished product needs to be read both now and by all participants, and then accompanying. Therefore, it makes sense to choose at least some fairly standard tools that will still be there for several years.

However, project documents are usually used to launch a project or system. After that, well-documented code, and some basic documents should be sufficient. I would probably pay more attention to organizing your documentation so people can easily find what they are looking for in the future. This may help provide some kind of standard repository structure / system for storing documentation, but it is not necessary to insist on all kinds of documentation templates. Focus on content, not tools.

Answer 2

A thorough discussion between leading developers or team members (perhaps written down later) is much more valuable than any document in my opinion. Give them the freedom to choose their tools and ask them only to write a short summary of high-level technical solutions at an early stage. This may be the basis of the documentation in the project. A technical design document expires too soon and takes too long to write.

Answer 3

I think there should be one set of tools and standards that are specified during the architecture that describe how design should be documented. It is very important to have a standard for documenting these things; otherwise, they usually fall on the sidelines; and if the project documentation is heterogeneous, there is a risk that people who really need to know most about design may not be able to find the design information that they really need when they really need it.

However, the choice of tools and standards depends entirely on each other organization; everything that works for the organization is suitable for them. As long as there is consistency in the standards (and to some extent), everything that is selected for a separate organization is suitable for them. It just needs to be solved and applied.

Answer 4

If your projects are not a cookie cutter, then it makes sense to use the best combination of tools for the job. Nevertheless, it is likely that some loose (rough recommendations) or narrow (applicable to specific circumstances) standards are required.