Documentation & Its Types

• What is Documentation ?
• Types of Documentation ? Explain each type of documentation

• Why it plays a crucial role in Software Development? 
• Best Practices that can help you to improve the quality.
• Basic Elements or Components that are must in Technical Documentation.

Types of Documentation

• Requirement Specification
• Architecture / Design  (High-Level Design)
• Technical Documentation (Low-Level Design)
• Release Notes / End User Manual.

Few parameters that need to a follow for effective documentation, irrespective of the type of document we are documenting

1. Easy to Read and Understand:- Don't use the vocabulary which is hard to understand for the users. In short, readability
2. Design / Graphical Element: - Try to use the graphical element such as tables, charts, flow diagrams instead of plain text.
3. Content:- Make sure the content is accurate, reliable and can be used. According to the different set of the audience, the content must fit accordingly.
4. Relevance:- Make sure it must be relevant to the work that the team is going to do.

One of the most important types of documentation in Software Engineering is Technical Documentation, it is the detailed description of the system, application which is in development. 

Technical Documentation

Technical Documentation refers to the documents which contain all the technical information about the project or product.  Documentation plays an important role as it helps us to visualize the roadmap for the work that is going to done and also helps the clients to understand what are the inputs they are providing and what will be the output in terms of an application or a system.

The technical information contains all the technical information that are going to be a crucial factor while development life cycle.

- It includes the all the technical diagrams (Usecase Diagrams, Sequential Diagram, Class Diagram, Dataflow Diagrams. and others)

- It includes the wireframes, object structure, and field level information.

- Object Structure means what object or tables are going to be used to maintain the data and records, and also, it includes how the different objects or tables will be related to each other.

- Field Level information contains what information are captured for each field, Basic information of that field ie Unique name of the field, what are the validations applied, what is the type of information going to be captured by that field, also what are the dependencies on this field. 

Technical Information also lets the technical team what tools and technologies are going to be used.

Also, Technical documentation also contains the information from the source code

• List of all the classes.
• Description and functionalities included in these classes
• All the functions in a specific class
• What are the parameters need to be passed
• Type of access modifiers given to the classes
• Dependencies between two classes and much more.

There are two types of Technical Documentation

1. Literate Programming
2. Elucidative Programming

Literate Programming is an approach to programming introduced by Donald Knuth in which the coder write down the comments or explain the logic and functionality of the code in the general language, which helps each and everyone to better understand the code.

Elucidative Programming is the result of practical applications of Literate Programming in real programming contexts. The Elucidative paradigm proposes that source code and documentation be stored separately.

 Levels of Documentation

For developing a perfect application or a system following documents are mandatory in the following sequence:

1. URS ( User Requirements Specification): The URS contains all the points from the customers which describe all the requirements that the software needs to perform.
2. SRS (System Requirements Specification): The SRS is the more of a technical document which contains the technical terms which are derived from the URS.
3. Wireframes and Technical Designs: Depending on the URS and SRS we need to design and create wireframes of all the UI components including  pages, wizards, forms, landing pages and emails that need to send out from the system. This also includes error messages, pop-up messages, content, images, and much other content related documents.
4. STC (System Test Cases): Once we have finalized SRS and URS from the client, development and documentation begin in parallel. Developer team begins with the development whereas the Quality Assurance team begins with the documentation of the test cases against the SRS and URS.  System Test Cases make sure that each and every requirement is begin taken care, also this helps the quality team to make sure that the system is performing all the desired functions for which it is being developed.
5. UAT (User Acceptance Testing): It is a procedure which is mostly done at the client side in which the client make sure that all the points and requirements given in URS and SRS are being handled properly and the system is same as what was required. Once accepted the system is all set and ready for the final deployment to production ie going live for the end users.
6. DTL (Defect Track Log): No system or application is perfect. Each one has their own set of defects, bugs or improvements. Quality Assurance team do document this defects, bugs or improvement and according to the priority and severity they are scheduled in the future sprints. Sometimes it might be possible that the issues, bugs found needs to be fixed in the same sprint, in that case, one more round of testing and UAT is done and the technical team makes sure that everything is working perfectly.
7. This is very much similar as of Backlog issues in JIRA. DTL don't always have the list of defects, bugs or improvements but sometimes few features of a system are left out because of less priority and due to time constraints, hence they are also tracked in the same document. 
8. Release Notes: Every product has new features and functions, system requirements, and installation instructions that users should be aware of. The best way to communicate the information is with Release Notes as a separate document which contains all the information which need to be conveyed to the end users. Release notes contain specific information about a particular product version such as system requirements, installation, new features and functions, changes to the product or release, and contact information.
9. User Manual & Guide: A user guide provides information about how to use features and functions, procedures to perform a variety of tasks, and tips to solve common problems. The user guide might be delivered as PDF on CD-ROM, hard copy, or as help files embedded in the application or system.

In next part of this documentation, I will be posting some of the standard templates for each type of documents and also what different types of documents can be helpful for us in effective and efficient Project Management.

In case if any one has any suggestion or queries, do let me know on parag.vyas209@gmail.com