Documentation: Written Description of a Computer Program

An in-depth exploration of various types of documentation associated with computer programs, including internal comments, on-line help, reference cards, manuals, and tutorials.

Documentation refers to the comprehensive written descriptions that accompany computer programs, providing vital information about their functionality, usage, and underlying logic. This documentation serves several purposes, from aiding developers in understanding the code to assisting end-users in efficiently operating the software.

Types of Documentation

Documentation can be categorized into several types based on its purpose and audience:

Internal Documentation

Internal documentation consists primarily of comments embedded in the source code. This form of documentation aids developers in understanding the purpose and functionality of code segments.

1def factorial(n):
2    if n == 0:
3        return 1
4    else:
5        return n * factorial(n-1)

Key features:

• Enhances code readability.
• Facilitates maintenance and updates.
• Essential for team-based projects where multiple developers may work on the same code.

On-line Documentation

On-line documentation is displayed interactively as the program runs, or can be accessed through in-program commands like HELP.

Examples:

• Context-sensitive help dialogs.
• Tooltips for specific user interface elements.
• Interactive user guides accessible via a HELP command.

Key features:

• Provides real-time assistance.
• Enhances user experience by offering instant support.

Reference Cards (Cheat Sheets)

Reference cards provide quick access to frequently used information and program commands.

Examples:

• Key command shortcuts for complex software like Adobe Photoshop.
• Syntax and function references for programming languages.

Key features:

• Easily accessible and quickly referable.
• Ideal for experienced users who need a quick refresher.

Reference Manuals

Reference manuals contain exhaustive information about the software, systematically detailing every function, feature, and option.

Examples:

• Comprehensive user manuals provided with complex enterprise software.
• Detailed API documentation for software development kits (SDKs).

Key features:

• In-depth, structured documentation covering all aspects of the software.
• Often includes step-by-step instructions, detailed explanations, and troubleshooting tips.

Tutorials

Tutorials serve as introductory guides, often accompanied by practical exercises to help new users learn how to use the software effectively.

Examples:

• Step-by-step guides included with new software packages.
• Interactive online tutorials available on educational platforms.

Key features:

• Generally structured as learning modules or lessons.
• Often include visual aids, examples, and practice exercises.

FAQs

Why is internal documentation important?

Internal documentation is crucial for maintaining the readability and maintainability of code. It allows developers to understand, update, and debug code more efficiently, especially in collaborative environments.

How does on-line documentation improve user experience?

On-line documentation provides users with real-time assistance, making it easier to navigate and utilize the software without needing to refer to external sources.

When should reference cards be used instead of reference manuals?

Reference cards are best used for quick look-ups and reminders of essential commands, while reference manuals are more suitable for understanding comprehensive and detailed functionalities.

Summary

Documentation in computer programs is an essential aspect that ensures both developers and end-users can effectively utilize and understand software. By categorizing documentation into internal comments, on-line help, reference cards, comprehensive manuals, and tutorials, developers and educators can cater to a wide range of needs, facilitating smoother software development and user interaction.

References

1. Sommerville, Ian. Software Engineering. 10th ed., Pearson, 2015.
2. McConnell, Steve. Code Complete: A Practical Handbook of Software Construction. 2nd ed., Microsoft Press, 2004.
3. ISO/IEC/IEEE 26515-2018: “Systems and software engineering — Developing information for users in an agile environment”.

Explore more on documentation best practices and advanced strategies for maintaining high-quality software documentation.