Modern computer programs written in high-level programming languages are often complex to use and understand, especially for users who are not familiar with the concept of software development. In a bid to increase a program’s usability, software developers now incorporate how-to instructions and help texts known as program documentation which makes them easier to use. In software engineering, program documentation is categorized into two major classes; external program documentation and non-executable code additives known as internal documentation.
External documentation refers to the user manuals and pamphlets packaged together with the software’s carrier case such as the installation manuals found inside the software’s compact disc casing. External documentation contains the software’s platform and hardware requirements specifications, design documents, and its development history (Dale & Weems, 2004). For instance, off-shelf programs like office suites and graphic editors developed for commercial purposes have manuals and booklets which specify basic requirements necessary for their successful installation and execution.
However, developer editions, release previews, and test pilots of the same proprietary versions encompass more detailed and technical external documentations. The information that can be found in this type of software documentation ranges from system compatibility issues, possible software loopholes, solved and unresolved defects, and resource usage summaries. The major purposes of a program’s external documentation are to increase program understandability, aid and quicken the software’s readability process and equip the user with basic troubleshooting skills (Lanier, 2008).
Pursuant to Mall (2009), internal documentation refers to the code comprehension features provided in the source code itself. Despite being incorporated inside the actual program, internal documentation is non-executable and thus does not affect the software’s operation. The chief objective of internal documentation is to simplify the software maintenance process whilst availing real-time support to the user.
Internal documentation contains information that is relevant to the working of the executable pieces of code. This information includes program functionality data, inputs attributes, and a statement of program constants and variables. It can be written in form of code indentation, comments, modules, and function headers, and in some cases, user-defined data types depending on the programming language being used (Mall, 2009).
External software documentation is intended for skilled software developers or maintenance analysts and can take two forms; explanatory or technical. Explanatory documentation exemplifies the actual working of a program’s piece of code or an entire module. On the other hand, technical documentation delves deeper and seeks not only to explain the working process of the software but also to show the logic behind an executable fragment of code or program module.
Embedding accurate internal documentation to a program’s executable lines of code requires strict adherence to the programming language’s syntax. Consequently, resource-intensive programs adopt a modular approach to internal documentation, thus exemplifying the influence of internal documentation on a program’s architecture.
Internal documentation can be used to assess the quality and usefulness of a program’s technical documentation (Wingkvist, Ericson & Lowe, 2011). Internal documentation is a vital source of reliable information necessary for effective software reengineering. It also forms the basis of platform compatibility checks. This means that a software developer can expand on a program’s ability to function on different platforms by adding or removing executable portions from the program without affecting its operational logic. Both internal and external documentation are vital components of software engineering and are considered infinite.
References
Dale, N., B. & Weems, C. (2004). Programming in C++ 3rd ed. Sudbury: Jones and Bartlett Publishers.
Lanier, C., R., (2008). Technical Communication and Programming: Internal and External Communication. Web.
Mall, R. (2009). Fundamentals of Software Engineering. New Delhi: PHI Learning.
Wingkvist, A., Ericson, M., & Lowe, W. (2011). A visualization-based Approach to Present and Assess Technical Documentation Quality. The Electronic Journal Information Systems Evaluation Volume 14 (1), 150-159.