Introduction
Technical specifications documents(TSD) plays a major role in conveying understanding of the project to any reader. Typically in the software industry there are two types of users who refer to TSD.
1..Developers, Project Managers who will be directly working on the Project
2. Client Personnels like Technical architect, CIO’s, Project Managers
I personally believe there should be two documents created for each intended audience. The reason is each set of user expects certain things from the document which may prove unnecessary to the other.
Document for customer overlook:
Generally customer approves the technical design, so it is obvious to convince the customer and assure him that all the technical details are covered in the document and system can meet desired goals. So while preparing document it is very necessary cover all such points those will help convincing the client techincal person. Technical architect from client will not be interested to know details at class levels or class diagrams, he will be interested to know Whether system is complying its requirements, those may be interms of
– Functionality,
– Performance,
– Deployement environment,
– Network requirements etc
and finally how you are depicting the overall architecture,
– Which technologies you are proposing,
– Is there any third party component used,
– Are there any licensing considerations,
– Need more hardware to be purchased
– Which best practices you are proposing etc .
So one should prepare a document may be consists of around 25-30 pages which will provide complete outlook of the system.
Document for Development team:
Development team is actual user of the document, they will be interested in knowing internals of the system. How system is divided into parts, how each part works, their dependencies, sequence, resuse, specific performance considerations, best practices and their details etc.It will be good if you can provide some sample programs and links to documentation sites for their further study.
Although, it differs from organization to organization whether single document is prepared or more than one. I am providing list of topics/areas those should be considered in the TSD.
1. Overall High Level Architecture(block diagrams)
2. Detail architecture(block diagrams)
3. Component diagram/architecture
4. Technological implementation of each component or module( if different languages used for respective module)
5. How components will be packaged and will be made ready for installation/deployment(Software Packing)
6. Sequence diagrams for important operations
7. Deployment methodology( e.g. clickonce deployment, XCOPY)
8. Folder structure( Development as well as deployment)
9. How components or assemblies would be versioned and source controlled
10. Dataflow diagrams
11. State Diagrams
12. Deployement diagrams
13. Network Architecture
14. How Logging /Event Logging/Email alerts will be implemented
15. How data( database, log files) purging will be done
16. Reporting methodology used(SSRS, CR and why?)
17. Naming conventions( Coding, assemblies, database objects)
18. Tiered and Layered Architecture
19. Security aspects and requirements( Application and network)
20. Performance aspects and requirements( Load testing methodology)
21. Pluggable and generic components
22. Highlight design patterns used
23. Database diagrams(ERD)
24. Disaster recovery plans and considerations in the application
25. Encryption methodology
26. How exceptions are handled
27. Class diagrams
28. Important algorithms
29. Usability Aspects
30. Data access technology proposed
31. Performance counters ( for troubleshooting)
Hope this is helpful !
Laxmikant Patil
Laxmikant Patil 