Documenting Software
The significance of documentation in software development cannot be overstated. It is often
argued that having thorough documentation is more vital than having perfect code. This is
because it is simpler to repair poorly written but well-documented code than to fix well-written
but poorly documented code. This highlights the critical role of comprehensive documentation in
supporting software systems.
The documentation needed to support software can be extensive, encompassing various aspects
such as internal code comments, systems analyses and design notes, figures, system
documentation, test plans, and user guides. Below are the essential areas that should be included
in your project documentation to support any software you create:
Start with an introduction or overview that provides a straightforward explanation of the
program, detailing its purpose and intended users. This sets the stage for the reader and provides
context for the rest of the documentation.
The technical solution adopted should be detailed next. This section should describe the
implemented technical solution, assess whether it is ideal, and consider alternative approaches.
This helps to understand the reasoning behind the chosen solution and its potential drawbacks.
The design section should include systems analysis and design, addressing human factors and
storyboards. This provides a visual and conceptual blueprint of the system and its components,
aiding in understanding the program's structure and flow.
Software engineering information is another critical aspect. This should cover the software's
structure, definition languages, and test plans. It provides a deeper technical insight into how the
software is built and tested.
The development approach used should also be documented. This involves describing the
development methodology used, such as evolutionary delivery or build and fix. Understanding
the development approach provides insights into the software's development process and
lifecycle.
Documenting problems encountered during development is also essential. This includes noting
any bugs, errors, and unfinished sections of code. Identifying these issues aids in troubleshooting
and future debugging efforts.
The limitations of the program should be clearly outlined. This involves detailing any
constraints, such as the maximum file size it can handle or the accuracy of results. It also
includes discussing the program's technical capabilities.
Hardware and software requirements for running the program should be listed. This ensures
that users are aware of the necessary environment to operate the software effectively.
The next stage section should offer guidance for future development. It should suggest areas for
enhancement and identify which parts of the software could be further developed. This section
Page | 1
should also evaluate if the code, documentation, and comments are at a level where someone else
could easily take over the project.
An evaluation of the software should be included to assess how well the software performs its
intended functions and whether it meets user needs. This evaluation provides feedback on the
software's effectiveness and usability.
For object-oriented programs, it is essential to document the classes and subclasses along with
their hierarchical relationships. This helps in understanding the program's object structure.
The database structure should be detailed, including tables and relationships between them.
This offers a clear view of how data is organized and managed within the program.
Where applicable, hardware diagrams should be included to provide a visual representation of
the hardware setup required.
A variable glossary should be provided, defining all variables used in the program. This helps in
understanding the role and value of each variable within the code.
Lastly, a user guide should be written at an appropriate level of detail for the intended user. This
guide helps users understand how to operate the software and utilize its features.
The level of detail required in each documentation area depends on the nature of the project.
Comprehensive analysis diagrams, test plans, and system documentation are necessary for
full-scale software development projects. However, projects that develop a piece of code merely
as a means of presenting ideas might not require such detailed documentation. Regardless of the
project's nature, commenting programs and writing user guides should always accompany any
piece of code produced.
The completion of documentation such as designs, analyses, and test plans depend on the
development process, methods employed, and the type of project undertaken. The primary focus
should be on ensuring that the documentation is comprehensive enough to support the software
effectively and facilitate future development and maintenance.
Page | 2
