What should go in technical specifications document ?


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