Documentation

Documentation Computer Programs Internal Documentation On-Line Documentation Reference Cards Reference Manuals Tutorials Command HELP
Documentation refers to the written descriptions and instructions for computer programs, serving various purposes such as user support, development assistance, and maintenance.
On this page

Definition

Documentation, in the context of computer programs, includes all written descriptions and instructions pertaining to computer software. It serves various purposes, such as providing support to users, aiding developers in maintaining and updating code, and ensuring that every aspect of the program is systematically and comprehensively covered. Documentation falls into several categories:

  1. Internal Documentation: Comments within the program code that help explain how the program functions, making it easier for developers to understand and maintain the software.
  2. On-line Documentation: Information displayed on-screen while the program runs or called up via commands like HELP, offering instant assistance to the user.
  3. Reference Cards: Concise documents containing easily forgotten details and quick commands for fast reference.
  4. Reference Manuals: Comprehensive documents setting out detailed instructions for the program in a systematic way.
  5. Tutorials: Guides introducing new users to the software, often providing step-by-step instructions.

Examples

  1. Internal Documentation Example:

    1# This function calculates the factorial of a number
2def factorial(n):
3    if n == 0:
4        return 1
5    else:
6        return n * factorial(n-1)

  2. On-line Documentation: Users can type HELP in the terminal to get immediate support and guidance on using specific commands or features.

  3. Reference Cards: A quick reference for a programming language might include basic syntax and commonly used functions.

  4. Reference Manuals: A comprehensive user manual for an accounting software might explain every feature in detail, including screenshots and examples.

  5. Tutorials: A beginner’s guide to a new software application, starting from installation and covering basic usage with visual aids.

Frequently Asked Questions (FAQs)

  1. Why is documentation important in software development? Documentation is crucial as it provides a clear and comprehensive guide for users and developers, ensuring the software can be effectively used and maintained.

  2. What is the difference between internal and on-line documentation? Internal documentation consists of comments within the code aimed at developers, while on-line documentation is meant for end-users and is often accessed through the software interface.

  3. How often should documentation be updated? Documentation should be updated whenever changes or updates are made to the software to ensure it remains accurate and useful.

  4. Can tutorials replace reference manuals? Tutorials and reference manuals serve different purposes; tutorials help new users get started, while reference manuals provide comprehensive, detailed information for all users.

  5. What makes good documentation? Clear, concise, and comprehensive information that is well-organized and easily accessible helps make good documentation.

  • API Documentation: Describes the functions, classes, return types, and arguments provided by an API.
  • Technical Writing: The craft of documenting complex technical processes in an easy-to-understand manner.
  • Version Control Systems: Tools like Git that help keep track of changes in the software and their documentation.

Online References

  1. W3Schools - Technical Writing Examples
  2. MDN Web Docs - Writing Documentation
  3. GitHub Guides - Mastering Markdown

Suggested Books for Further Study

  1. “The Elements of Style” by William Strunk Jr. and E.B. White
  2. “The Complete Idiot’s Guide to Technical Writing” by Krista Van Laan and Catherine Julian
  3. “Developing Quality Technical Information” by Gretchen Hargis and Michelle Carey

Fundamentals of Documentation: Computing Basics Quiz

### Which of the following best describes "Internal Documentation"? - [x] Comments within the program code. - [ ] User guides and reference manuals. - [ ] Interactive help prompts. - [ ] Video tutorials for software onboarding. > **Explanation:** Internal documentation consists of comments within the program code that help explain how the program functions. ### What command is often used to call up on-line documentation? - [ ] EXIT - [x] HELP - [ ] BEGIN - [ ] REPEAT > **Explanation:** The `HELP` command is frequently used to display on-line documentation providing immediate assistance to the user. ### What is the primary purpose of a reference card? - [ ] To provide step-by-step instructions for new users. - [ ] To display on-screen help while running the program. - [x] To offer quick access to frequently used commands and details. - [ ] To include comments within the program code. > **Explanation:** Reference cards contain frequently used commands and easily forgotten details for quick reference. ### What is a key characteristic of a reference manual? - [ ] Brief summaries of functions and commands. - [ ] Commented examples within the code. - [x] Comprehensive and systematic instructions for the program. - [ ] Interactive on-screen help. > **Explanation:** Reference manuals provide detailed and systematic instructions for the entire program. ### Which type of documentation aims primarily to assist new users in learning the software? - [ ] Internal Documentation - [ ] Reference Cards - [ ] On-line Documentation - [x] Tutorials > **Explanation:** Tutorials are designed to introduce new users to the software, usually through step-by-step instructions. ### How should documentation be maintained to remain useful? - [ ] By only updating it once every few years. - [ ] By leaving it unchanged as the software evolves. - [x] By updating it whenever the software is updated or changed. - [ ] By keeping it separate from the software development process. > **Explanation:** Documentation should be kept up-to-date with the software to ensure it remains accurate and useful. ### What is the main audience for internal documentation? - [x] Developers working on the software. - [ ] End-users of the software. - [ ] Marketing team promoting the software. - [ ] Technical support representatives. > **Explanation:** The main audience for internal documentation is developers, as it helps them understand and maintain the code. ### Why is documentation essential for effective software maintenance? - [x] It provides a clear guide for updates and bug fixes. - [ ] It serves solely as a marketing tool. - [ ] It is only useful for user interface designers. - [ ] It replaces the need for quality coding practices. > **Explanation:** Documentation provides essential information for updates, improvements, and bug fixes, which are critical for effective software maintenance. ### What makes tutorials different from other forms of documentation? - [ ] They are always the longest form of documentation. - [ ] They include detailed API information. - [x] They are designed to help new users get started quickly. - [ ] They contain internal code comments. > **Explanation:** Tutorials are specifically designed to help new users get started quickly, often through step-by-step instructions and practical examples. ### What type of content is typically found in a reference manual? - [ ] Casual use case scenarios and anecdotes. - [ ] Highly detailed, systematic instructions and information about the program. - [ ] Personal opinions from the developers. - [ ] Generic advice unrelated to the software. > **Explanation:** Reference manuals contain highly detailed, systematic instructions, often covering every aspect of the program comprehensively.

Thank you for exploring the comprehensive documentation for computer programs and engaging with our informative quiz! Enhance your technical writing skills for improved software usability and maintenance.

Wednesday, August 7, 2024
Dodd-Frank Act of 2010
Documentary Evidence
Software January 1, 1

Accounting Terms Lexicon

Discover comprehensive accounting definitions and practical insights. Empowering students and professionals with clear and concise explanations for a better understanding of financial terms.