Tuesday, January 8, 2008

Types of documentation

Documentation is an important part of software engineering that is often overlooked.


Types of documentation include:

· Architecture - Architectural overview of software; including relations to an environment, construction principles to be used in design and technical documentation, etc.

· Design - The design of software components.

· Technical - Documentation of code, algorithms, interfaces, APIs.

· End User - Manuals for the end-user.

· Operator - Manuals for the systems administrator.

· Application operator - Manuals for the "superuser" of the software.

· Help desk - Manuals for first and second line support.


Requirement analysis document:

In systems engineering, a requirement is a description of what a system should do. Systems may have from dozens to thousands of requirements.

A collection of requirements defines the characteristics or features of the desired (required) system, but generally avoids saying how the system should implement those requirements. Language in the requirements that describes how the system should be implemented is known as implementation bias.


Functional requirement specification

As defined in requirements engineering, functional requirements specify specific behaviors of a system. This should be contrasted with non-functional requirements which specify overall characteristics such as cost and reliability. (An alternative view is that functional requirements specify specific behavior while nonfunctional provide adjectives which may be used to describe these behaviors.)

Typically, a requirements analyst generates functional requirements after building use cases. A typical functional requirement will contain a unique name and number, a brief summary, and a rationale. This information is used to help the reader understand why the requirement is needed, and to track the requirement through the development of the system.


Code Documentation

This is what most programmers mean when using the term software documentation. When creating software, code alone is insufficient. There must be some text along with it to describe various aspects of its intended operation. This documentation is usually embedded within the source code itself so it is readily accessible to anyone who may be traversing it.

This writing can be highly technical and is mainly used to define and explain the APIs, data structures and algorithms. For example, one might use this documentation to explain that the variable m_name refers to the first and last name of a person. It is important for the code documents to be thorough, but not so verbose that it becomes difficult to maintain them.

Test Strategy:

The Test Strategy is the first document QA should prepare for any project. This is a living document that should be maintained /updated throughout the project. The first draft should be completed upon approval of the RAD and sent to the developer and technical product manager for review.

The Test Strategy is a high-level document that details the approach QA will follow in testing the given product. This document can vary based on the project, but all strategies should include the following criteria: Project Overview - What is the project?

Project Scope - What are the core components of the product to be tested?

Testing - This section defines the test methodology to be used, the types of testing to be executed (GUI, Functional, etc.), how testing will be prioritized, testing that will and will not be done and the associated risks. This section should also outline the system configurations that will be tested and the tester assignments for the project.

No comments: