Thursday, 3 March 2016

What Technical Specification document contain?

Introduction

What is technical specification? Technical requirement pertains to the technical aspects that your system must fulfill, such as performance-related issues, reliability issues, and availability issues.
Technical specifications documents(TSD) plays a major role in conveying understanding of the project to any reader in the software industry. There are usually  multiple  types of users/audiences who refer to technical specification document..

  1. Developers,Project Managers,Tech Leads and Technical Architects who will be directly working on the Project
  2. Client Personnel's like Technical architect, CIO’s, Project Managers to whom  project is delivered or  Project belongs

 I am  sure  that technical specification should  satisfy all the intended audiences/ users. There will be  certain things from the document which may prove unnecessary to the other because the way developer thinks is different from technical architect or customer.. So, better we can split document into two separate documents or document itself into two main sections. let we see how we will go for it

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 technical 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 in terms of

  1. Functionality: This section should include application functionality in detail with diagram
  2. Deployment environment: This section should include complete detailed diagram with explanation about deployment model.
  3. Depicting the overall architecture:this section i am explaining below..
  4. Technology Stack you are proposing with licensing considerations(if any):This section explains use of technologies,languages and databases and how they fit in this project along with licensing details if any.
  5. Is there any third party component used:This section gives overview of third party components/services used
  6. Need more infrastructure/hardware to be purchased:This section explains need of hardware to be purchased for this project deployment
  7. Platform Required:This section gives details about O/S,Servers,databases required for this project to run

So one should prepare a document should give complete outlook of the system and no of pages may vary depending on project. Here is detailed table which gives overview of no of pages we can have in technical specification document

PROJECT SIZE NUMBER OF DOCUMENTS
SMALL 10-15
MEDIUM 15-20
LARGE 20-40

 Document for Development team:

Development team is real audience or user of the technical document, they will be interested in knowing how system has been developed on low level like how classes modules packages or namespaces are written and related to each other. So, the document should give some detailed insight about  how each component/module  works, their dependencies,  reuse , performance considerations and  best practices.

Well, i also do believe that taste changes from organization what all needs to be provided. Thinking honestly ,I experienced list of below sections are required in TSD.

  1. Introduction :This section should dive brief introduction about application/project
  2. Overall High Level Architecture(block diagrams): This section should include overall high level architecture which includes layers and components used for designing/developing application



  3. Detail architecture(block diagrams): This section shows Low level design of the system which includes components and respective classes used



  4. Component diagram/architecture: This section gives details about components of each layer and their interaction,you can use UML/Visio or any free tool to design components,classes and interfaces interaction and dependency.



  5. Technological implementation of each component or module( if different languages used for respective module)
  6. Deployment methodology( e.g. click once deployment, X COPY) and How components will be packaged and will be made ready for installation/deployment(Software Packing)
  7. Sequence Diagrams: UML sequence diagrams are used to show how objects interact in a given situation. An important characteristic of a sequence diagram is that time passes from top to bottom : the interaction starts near the top of the diagram and ends at the bottom



  8. Deployment diagrams:This section should include complete deployment diagram which will describe the hardware components where software components are deployed. Component diagrams and deployment diagrams are closely related. Component diagrams are used to describe the components and deployment diagrams shows how they are deployed in hardware. UML is mainly designed to focus on software artifacts of a system. But these two diagrams are special diagrams used to focus on software components and hardware components. Deployment diagrams are useful for system engineers. An efficient deployment diagram is very important because it controls the following parameters
    1. Performance
    2. Scalability
    3. Maintainability
    4. Portability



  9. Naming conventions( Coding, assemblies, database objects): here you have to give some small examples of your code with coding standards like the way you are defining classes,methods,variable...
  10. Tiered and Layered Architecture :Here you should show layers of the application and make sure that you are explaining whether your application layer can be deployed on multiple services independently.
  11. Database diagrams(ERD): You can use Database server or other architect tool for database diagram generation and include them in TDS . Here you can show ERD diagram which will include all database table with relation..


  12. How exceptions are handled: Here you will explain Exception handling in detail like whether you are using any utility like log4net or custom application level exception handling .You should document every exception that might be thrown by your code, including those in any methods that you might call.
  13. Class diagrams: You can use VS or eclipse or any free tool for class generation and include them in TDS . Class diagrams look like as shown below


  14. Data access technology proposed like ADO.NET ,Entity framework ,hibernate ,JDO,JDBC API and reason behind choosing the data access technology

Final Word

A technical specification is a document that defines a set of requirements that a product or assembly must meet or exceed. A product or assembly that does not meet all of the specifically expressed requirements does not meet the specification, and often is referred to as being out of specification or "out of spec."