Scribd
Upload
854 views7 pages

Software Documentation-Internal and External

The document discusses the importance of software documentation, which includes both internal documentation within the source code itself as well as external supporting documents. Good documentation enhances understandability, maintainability, and usability. It also helps manage turnover and track project progress. Internal documentation includes comments, meaningful names, headers, and structure within the code. External documents include requirements, design, user manuals, and test documents, which should be consistently updated with the code.

Uploaded by

Bini Lyngdoh
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
854 views7 pages

Software Documentation-Internal and External

The document discusses the importance of software documentation, which includes both internal documentation within the source code itself as well as external supporting documents. Good documentation enhances understandability, maintainability, and usability. It also helps manage turnover and track project progress. Internal documentation includes comments, meaningful names, headers, and structure within the code. External documents include requirements, design, user manuals, and test documents, which should be consistently updated with the code.

Uploaded by

Bini Lyngdoh
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 7

Software Documentation

 Software engineering process does not include only the


development of executable files and the source code ,but it
also includes development of a various kinds of documents
such as users’ manual, software requirements
specification (SRS) document, design document, test
document, installation manual, etc.
 All these documents are considered a vital part of good
software development practice.
Software Documentation
 Good documents are helpful in the following ways:
 They enhance understandability and maintainability of a
software product.
 They reduce the effort and time required for maintenance.
 They help the users to understand and effectively use the
system.
 Good documents help to effectively tackle the manpower
turnover problem. Even when an engineer leaves the
organization, and a new engineer comes in, he can build up
the required knowledge easily by referring to the documents.
 Production of good documents helps the manager to
effectively track the progress of the project.
 The project manager knows that measurable progress has
been achieved, if the result of some pieces of work has been
documented and reviewed.
Types of software documents
 Different types of software documents can broadly be
classified into the following:
 Internal documentation: These provides source code itself.
 External documentation : These are supporting documents
such as SRS document, user manual, design document and
test document.
Internal documentation :
 Internal documentation is the code comprehension
features provided as part of the source code itself.
 Internal documentation can be provided in the code in
several forms.
 The important types of internal documentation are as
follows:
 Comments embedded in source code.
 Use of meaningful variable names
 Module and function headers.
 Code indentation
 Code structuring (i.e, code decomposed into
modules and functions).
 Use of enumerated types.
 Use of constant identifiers.
 Use of user-defined data types.
 Careful experiments suggest that out of all types of internal
documentation, meaningful variable names is most
useful in understanding a piece of code.
 This is of course in contrast to the common expectation
that code commenting would be the most useful.
 The research finding is obviously true when comments are
written without thought.
 For example, the following style of code commenting does not
in any way help in understanding the code.
a = 10; /* a made 10 */
 But even when code is carefully commented, meaningful
variable names still are more helpful in understanding a piece
of code.
 Good software development organizations usually ensure
good internal documentation by appropriately formulating
their coding standards and coding guidelines.
External documentation:
 External documentation is provided through various types of
supporting documents such as users’ manual, software
requirements specification document, design
document, test documents, etc.
 A systematic software development style ensures that all these
documents are produced in an orderly fashion.
 An important feature required for good external
documentation is consistency with the code.
 All the documents developed for a product should be up-
to-date and every change made to the code should be
reflected in the relevant external documents.
 Even if only a few documents are not up-to date, they create
inconsistency and lead to confusion.

You might also like