concerned with re-implementing legacy systems to make them more maintainable.
Re-engineering may involve re-documenting the system, organising and restructuring the system, translating the system to a more modern programming language and modifying and updating the structure and values of the system’s data.
The functionality of the software is not changed and, normally, the system architecture also remains the same.
The critical distinction between re-engineering and new software development is the starting point for the development. Rather than start with a written specification, the old system acts as a specification for the new system.
Reengineering includes:
Source code translation: The program is converted from an old programming language to a more modern version of the same language or to a different language.
Reverse engineering: The program is analysed and information extracted from it which helps to document its organisation and functionality. is the process of deriving a systems design and specification from its source code.
Program structure improvement: The control structure of the program is analysed and modified to make it easier to read and understand. involves replacing unstructured control constructs such as gotos with while loops and simple conditional statements
program modularisation: Related parts of the program are grouped together and, where appropriate, redundancy is removed. In some cases, this stage may involve architectural transformation.
Data re-engineering: The data processed by the program is changed to reflect program changes. may be necessary because of inconsistent data management by the programs in a legacy system. The objective of data reengineering may be to re-engineer all programs to use a common database.
The costs of data re-engineering are significantly increased if existing data has to be converted to some new format.
different types of documents from informal working documents through to professionally produced user manuals.
software engineers and professional technical writers are responsible for the documentation of software systems.
for large projects, documentation starts before development as proposal to the development process.
The set of documents that you have to produce for any system depends on the contract with the client for the system, the type of system being developed and its expected lifetime, the culture and size of the company developing the system and the development schedule that it expected.
types of documentations:
Process documentation:
These documents record the process of development and maintenance. Plans, schedules, process quality documents and organizational and project standards are process documentation.
An important goal of agile approaches is to minimize the amount of process documentation produced as this adds overhead without contributing to the functionality of the system being developed.
Product documentation:
This documentation describes the product that is being developed. System documentation describes the product from the point of view of the engineers developing and maintaining the system; user documentation provides a product description that is oriented towards system users.
Product documentation is used after the system is operational but is also essential for management of the system development.
system specification is part of the product documentation.
Documentation may also be required for long-lifetime systems, irrespective of the development technique used.
Plans, estimates and schedules: These are documents produced by managers which are used to predict and to control the software process.
Reports: These are documents which report how resources were used during the process of development.
Standards: These are documents which set out how the process is to be implemented. These may be developed from organizational, national or international standards.
Working papers: These are often the principal technical communication documents in a project. They record the ideas and thoughts of the engineers working on the project, are interim versions of product documentation, describe implementation strategies and set out problems which have been identified. They often, implicitly, record the rationale for design decisions.
E-mail messages, wikis, etc: These record the details of everyday communications between managers and development engineers.
The major characteristic of process documentation is that most of it becomes outdated
If a system is externally regulated and has to be certified before it is used, the regulator may require the production of process documentation to demonstrate that good practice has been followed in the development of the system.
some important process documentation that should not be opted out:
test schedules are of value during software evolution as they act as a basis for re-planning the validation of system changes.
Working papers, which explain the reasons behind design decisions (design rationale).
Product documentation is concerned with describing the delivered software product.
it has a relatively long life.
types of product documentation:
User documentation:
tells the users how to use the software product.
designed for end-users and system administrators.
System documentation:
principally intended for maintenance engineers.
includes all of the documents describing the system itself from the requirements specification to the final acceptance test plan.
system documentation should include:
The requirements document and an associated rationale.
A document describing the system architecture.
For each program in the system, a description of the architecture of that program.
For each component in the system, a description of its functionality and interfaces.
Program source code listings: comments on the source code, explain complex logic, justify programming method used, meaningful variable names, code should self-documenting, etc.
Validation documents describing how each program is validated and how the validation information relates to the requirements. for quality assurance.
A system maintenance guide: which describes known problems with the system, describes which parts of the system are hardware and software dependent and which describes how evolution of the system has been taken into account in its design.
The document structure is the way in which the material in the document is organized into chapters and, within these chapters, into sections and sub-sections.
The IEEE standard for user documentation is (IEEE, 2001)
minimum structure required:
cover page: which identifies the project, the document, the author, the date of production, the type of document, configuration management and quality assurance information, the intended recipients of the document, and the confidentiality class of the document.
Documents that are more than a few pages long should be divided into chapters with each chapter structured into sections and sub-sections. contents page should be produced listing these chapters, sections and sub-sections.
If a document contains a lot of detailed, reference information it should have an index.
If a document is intended for a wide spectrum of readers who may have differing vocabularies, a glossary should be provided which defines the technical terms and acronyms used in the document.
writing style:
Written work must be written, read, criticized and then rewritten until a satisfactory document is produced.
Documents should be inspected in the same way as programs.
Documentation standards:
Process standards:
These standards define the process that should be followed for high-quality document production.
Product standards:
These are standards that govern the documents themselves e.g. their organization and structure.
Documents should have a consistent appearance and, documents of the same class should have a consistent structure.
Interchange standards:
to ensure that all electronic copies of documents are compatible.
The IEEE standard for user documentation:
The first IEEE standard for user documentation (IEEE, 1987).
