What Technical Specification document contain?
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..
- Developers,Project Managers,Tech Leads and Technical Architects who will be directly working on the Project
- Client Personnels 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 archtect or customer.. So, better we can split document into two sepeate 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 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: This section should include application functionality in detail with diagram
- Deployement environment: This section should include complete detailed diagram with explaination about deployement model.
- Depicting the overall architecture:this section i am explaining below..
- 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 licencing details if any.
- Is there any third party component used:This section gives overview of third party components/services used
- Need more infrastructure/hardware to be purchased:This section explains need of hardware to be purchased for this project deployment
- 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|
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 wriiten and related to each other. So, the document should give some detailed insight about how each component/module works, their dependencies, resuse , performance considerations and best practices
organization what all neds to be provided. Thinking honestly ,I experirnced list of below sections are required in TSD.
- Introduction :This section should dive brief introduction about application/project
Overall High Level Architecture(block diagrams):
This section should include overall high level architecture which
includes layers and components used for designing/developing application
Detail architecture(block diagrams): This section shows Low level design of the system which includes compobnents and respective classes used
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.
- Technological implementation of each component or module( if different languages used for respective module)
- Deployment methodology( e.g. clickonce deployment, XCOPY) and How components will be packaged and will be made ready for installation/deployment(Software Packing)
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
Deployement 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
- 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,varaible...
- 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.
Database diagrams(ERD): You can use Database server or other architect tool for database diagram genaration
and include them in TDS . Here you can show ERD diagram which will inlude all
database table with relation..
- How exceptions are handled: Here you will explain Exception handlling 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.
Class diagrams: You can use VS or eclise or any free tool for class genaration
and include them in TDS . Class diagrams look like as shown below
- Data access technology proposed like ADO.NET ,Entity framework ,hybernate ,JDO,JDBC API and reson behind choosing the data access technology
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."