System Documentation

Introduction

Definition

Characteristics

• The document of a system communicates the details about the system to different connected or related audiences. It explains the system. The ever-increasing complexity of information systems requires emphasis on well-established systems of documentation.
• Documentation becomes part of each step of system development throughout the process of system development even before the documentation starts officially.
• During the process of system development, study reports and other necessary information are documented to help people involved in system development to understand the process.
• Documentation should not be seen as an overhead for system development. Rather, documentation has to be seen as an investment for the development of high-quality software.
• Any software project is associated with a large number of documents depending on the complexity of the project. Documentation that is associated with system development has several requirements.

Need/Importance of Documentation

Types of Documentation/Document

• Various necessary documents like System requirement specification (SRS), System Design Specification (SDS), Test Design Document, and User Manuals are normally produced during the life cycle of a software development process of a complex system.
• There are many kinds of documentation namely –
  • System Requirements Specification(SRS) Documentation/Documents

Link for SRS More Details

• • Analysis Documentation/Document

Link for Analysis Document More Details

•  
  • Design Documentation/System Design Specification (SDS) Document

Link for SDS More Details

• • Interface Documentation/Document
    • Interface documentation is a critical part of software development that describes how different software components, systems, or modules interact with each other.
    • Interface documentation is essential for ensuring that software components can communicate and interact effectively.
    • It provides detailed guidance on how to use an interface, what data it requires, how it handles errors, and how it ensures security.
    • By following best practices and keeping the documentation clear, consistent, and up-to-date, you ensure that all stakeholders can effectively use and integrate the system’s components.
    • This documentation provides the necessary details to developers, testers, and integrators to ensure that the components can communicate effectively, exchange data correctly, and work together seamlessly.
    • This document defines how different systems or components will communicate, including data formats, protocols, and methods.
    • This document helps developers integrate different components or systems by providing clear guidelines on how interfaces should be used.
    • This document ensures that all system parts interact consistently, reducing the likelihood of errors or integration issues.
    • This document provides a reference for future maintenance and updates, making modifying or extending the system without breaking existing functionality easier.
    • It includes an introduction, an overview of the Interface, interface specification(data structures, function, etc), protocols and standards, security considerations, error handling, testing & validations, appendices, etc.

    • Criteria for Interface Documentation

      • Clarity and Precision: It should be ensured that the documentation is unambiguous and try to avoid jargon and be precise in describing the interface’s behavior.
      • Consistency: It is suggested to maintain consistency in terminology, structure, and formatting throughout the documentation.
      • Keep It Up-to-Date: It is believed that documentation should be regularly updated to reflect changes in the interface, such as new methods, deprecated features, or updated security practices.
      • Use Visual Aids: It is suggested that where appropriate, include diagrams, flowcharts, or tables to help illustrate complex interactions or data flows.
      • Accessibility: Try to make the documentation easily accessible to all intended users in their simple format, whether it’s through a web-based interface, PDF, or other means.
  • Internal Program Documentation/Document
    • Internal Program Documentation is crucial for the successful development, maintenance, and scaling of software applications.
    • By providing clear, concise, and relevant documentation within the code, developers can ensure that their work is easily understood, maintained, and extended by others.
    • Using best practices in this documentation not only improves the quality of the software but also enhances collaboration and reduces the likelihood of errors in the long term.
    • Internal program documentation is essential for understanding, maintaining, and updating software code.
    • It refers to the comments, annotations, and explanations embedded directly within the codebase, as well as any associated technical documents that describe the software’s structure, logic, and functionality.
    • This documentation is primarily intended for developers and technical stakeholders who work on or interact with the code, either during initial development or throughout the software’s lifecycle.
    • Internal Program Documentation is a set of documents, comments, and annotations within the source code of a software application that provides developers with insights into the design, structure, and logic of the code.
    • This documentation is vital for the maintainability, scalability, and understandability of the software, especially when multiple developers are involved, or when the software needs to be updated or debugged in the future.
    • This documentation helps developers quickly understand the purpose and functionality of different parts of the code.
    • This documentation makes it easier to maintain, update, and refactor the code by providing clear explanations of how the code works.
    • This documentation assists in identifying and fixing bugs by explaining the logic and flow of the program.
    • This documentation mainly includes code comments, method and function documentation, class and module documentation, variable and data structure documentation, algorithm and logic documentation, Configuration and Metadata Documentation, Version Control Annotations, etc. processes.
    • To make a good Internal Program Documentation –
      • Documentation should be concise and directly related to the code.
      • Avoid unnecessary comments that do not add value.
      • Use clear, simple language, and maintain consistency in terminology and style throughout the documentation.
      • Focus on explaining why the code is written a certain way, not just what it does. This helps future developers understand the rationale behind decisions.
      • Utilize tools like Javadoc for Java, Doxygen for C++, or Sphinx for Python to generate consistent and structured documentation from the codebase.
  • Test Design Documentation(TDD)/Document
    • Test Design Documentation is a critical element in the software testing process, providing a structured and detailed plan for how testing will be conducted.
    • By carefully planning and documenting the testing approach, teams can ensure thorough testing coverage, effective defect management, and clear communication with all stakeholders.
    • Test Design Documentation is a detailed document that outlines how the testing process for a software application will be conducted.
    • It includes the plan, scope, approach, resources, and schedule for the testing activities, and serves as a blueprint for the testing team to ensure comprehensive coverage and effective testing of the system.
    • This document is crucial for maintaining a structured and organized approach to testing, ensuring that all aspects of the software are thoroughly tested and that any issues are identified and resolved.
    • This documentation outlines the approach and methodology that will be used to test the software.
    • This documentation ensures that all aspects of the software, including functionality, performance, security, and usability, are covered.
    • This document provides a clear and detailed plan that can be communicated to all stakeholders, ensuring alignment on the testing approach.
    • Using the best practices in creating and maintaining this document is key to the success of the testing phase and, ultimately, the quality of the final software product.
    • For creating the best test design documentation – 
      • The document should be clear and detailed enough that any member of the team can understand and follow it.
      • The document should be kept up-to-date with any changes in the project or testing process.
      • The document should involve key stakeholders in the review process to ensure all requirements and concerns are addressed.
      • The document should structure the document into well-organized sections and subsections to make it easy to navigate and update.
    • Test Design Documentation includes an Introduction, Test objectives, Test Scope, Test Strategy(Test levels, Test types, Test design techniques, etc), Test environments, Test cases, Defect Management, Risk Analysis, Test metrics & reporting,  Test team roles and responsibilities, Appendices, etc.
  • User-Oriented Documentation/User Manual Document

Link for More User Manual Details

Stages of Documentation Process

Documentation Standards (ISO and IEEE)

• One basic goal of documentation standards using software engineering is to produce the best possible working software along with the best possible supporting documentation.
• This software documentation standard is used in the organization for uniform practices for documentation preparation, interpretation, change, and revision, to ensure the inclusion of essential requirements of different standards.
• Sometimes, documentation as per various standards is stated in the contractual agreement between the software vendor and the customer.
• The software life cycle process describes documentation as one of the supporting parallel processes of the software development process.

Types of Documentation Standards

• The following are different documentation standards:-

  • ISO/IEC (International Standard Organization/International Electrotechnical Commission)12207: 

    • This standard is not a documentation standard but describes the process of documentation during the software development process.
    • This standard describes documentation “as a supporting activity to record information produced by a system development life cycle process.”

  • ISO/IEC 18019:

    • This standard describes and guidelines for the design and preparation of user documentation for application software.
    • This standard describes how to establish what information users need, how to determine how that information should be presented to the users, and then how to prepare the information and make it available.
    • It covers both online and printed documentation.
    • It describes the standard format and style to be adopted for documentation.
    • It gives principles and recommended practices for documentation.

  • ISO/IEC 15910:

    • This standard describes the Software user documentation process.
    • This standard specifies the minimum process for creating user documentation for software that has a user interface, including printed documentation (e.g., user manuals), online documentation, help text, and online documentation systems.

  • IEEE 1063:

    • This standard is considered Software User Documentation.
    • It provides minimum requirements for structure, information content, and format for user documentation.
    • It does not describe the process to be adopted for documentation.
    • It is applicable for both printed and online documentation.

Use/Application of Documentation