💻 Comprehensive IGCSE ICT Study Notes: Documentation (Section 7.5 of The Systems Life Cycle)
Hello! Welcome to the final stage of our journey through the Systems Life Cycle. You've analyzed, designed, tested, and implemented a new system. But wait—how will people know how to use it, and how will future programmers fix it? That’s where Documentation comes in!
In this chapter, we will learn why good documentation is crucial, and we’ll break down the two essential types: the detailed blueprint for the IT experts (Technical) and the friendly instruction manual for the users (User).
📜 7.5 What is Documentation?
Documentation refers to the written descriptions, instructions, and guides that explain how an ICT system works, how it was built, and how it should be used.
Think of building a massive Lego castle: you need the simple picture guide (User Documentation) to assemble it, and you need the detailed list of every single brick and connector (Technical Documentation) if you ever need to expand it or replace a missing piece.
There are two main types of documentation you need to know about:
- Technical Documentation (for the IT professionals)
- User Documentation (for the people who actually use the system)
Key Takeaway: Documentation ensures the system can be used, maintained, and modified long after the original developer is gone.
📝 Section 1: Technical Documentation (The Developer's Handbook)
Technical Documentation (often called System Documentation) is written for the people who manage, maintain, and potentially modify the system. This audience includes the original programmers, system analysts, and future IT support staff.
Purpose of Technical Documentation
The main goal is to provide enough detail that an IT professional, who may never have seen the system before, can understand how every part of the system is structured and operates.
- To help IT staff maintain the system (keep it running smoothly).
- To allow developers to easily debug (fix errors) or modify (add new features) the system.
- To ensure consistency and quality across the system's lifetime.
💪 Key Components of Technical Documentation
This section is detailed, so we'll break down exactly what needs to be included:
1. System Overview and Requirements
- Purpose of the system/program: A clear statement of what the software is supposed to achieve (e.g., "The system manages inventory stock and automates reordering.").
- Limitations of the system: What the system cannot do (e.g., "The system can only handle 10,000 active records," or "It cannot calculate taxes.").
- Hardware and software requirements: A list of the minimum computer equipment (CPU, RAM, storage) and operating system/utility programs required to run and maintain the software.
2. Design and Logic
- System Flowcharts: Visual diagrams showing how data flows through the entire system and its various processes.
- Program Flowcharts/Algorithms: Detailed diagrams or step-by-step instructions showing the logic within individual programs or modules.
- Program Listing: The actual source code written in the Program Language used (e.g., Python, C++, SQL).
3. Data Structure and Validation
- File Structures: Details of how data is organised, including table names, relationships, and index keys (like Primary Keys).
- List of variables: A glossary listing all variables used, explaining their name, data type (e.g., Integer, Text, Boolean), and purpose.
- Input format and Output format: Descriptions or diagrams showing exactly what data is inputted (data capture forms) and how the final results are displayed (report layouts).
- Validation Routines: The specific rules applied to inputs (e.g., Range check, Length check, Check digit).
4. Testing Information
- Sample runs/Test runs: Examples of test data used, showing the expected outcomes and the actual outcomes recorded during testing.
Audience: Programmers & IT Staff.
Focus: How the system is built, its internal logic (flowcharts, code), and data handling (file structures, validation).
📖 Section 2: User Documentation (The Instruction Manual)
User Documentation is designed for the end-user—the person who sits down and uses the software every day to perform their job. This documentation must be easy to read, free of technical jargon, and focus on practical steps.
Don't worry if this seems tricky at first! Remember, the key difference is the audience. If your mum or younger sibling could use the instructions to operate the software, it's good user documentation!
Purpose of User Documentation
The main goal is to ensure the user can operate the system effectively and confidently without needing constant help from the IT department.
- To explain how to operate the software (step-by-step guides).
- To help the user recover when they make a mistake or encounter an error.
- To introduce the system's capabilities in a simple manner.
💪 Key Components of User Documentation
User documentation can be provided in different formats, such as a paper manual, a help file within the software, or a website/wiki.
1. Getting Started
- Purpose of the system: A simple explanation of what the system does.
- Limitations of the system: What the user can expect and what the system won't handle.
- Hardware and software requirements: A quick reference for what is needed to run the software.
- How to load/run/install software: Step-by-step instructions for getting the program set up and running.
2. Operational Guides (How-Tos)
- How to save a file or print data: Basic, necessary instructions for interacting with data.
- How to add/delete/edit records: Detailed, numbered steps showing the user how to manipulate the data they are responsible for.
- Input format and Output format: Examples or screenshots showing the user what data capture forms look like and what reports they can expect to see.
- Sample runs: Simple examples showing what the screen should look like when a specific task is completed successfully.
3. Dealing with Problems
- Error messages and Error handling: A list of common messages the user might see (e.g., "Data entered is invalid") and clear instructions on what they should do to fix the problem.
- Troubleshooting guide/helpline: A section dedicated to solving common issues, often including contact information for support.
- Frequently Asked Questions (FAQs): Answers to common user queries.
- Glossary of terms: Simple definitions for any specific terminology used within the software (e.g., what does 'Query' mean?).
Audience: End-Users (Non-technical staff).
Focus: Practical steps (how to run/save/print), troubleshooting, and simple explanations.
📌 Comparing Technical and User Documentation
The exam often asks you to compare the two types or justify why certain components are needed in one type but not the other. Here is the critical difference:
Technical vs. User Documentation (Quick Comparison)
-
Technical: Focuses on "How was it built?"
Example Content: Program Language, File Structures, Flowcharts. -
User: Focuses on "How do I use it?"
Example Content: How to print, Troubleshooting guide, FAQs.
Did you know? Many modern companies are moving away from traditional paper manuals and using context-sensitive help, where pressing F1 or clicking a question mark button immediately brings up documentation relevant to the specific screen you are looking at. This is very popular in User Documentation!
***
Final Key Takeaway
Documentation is the essential link between the development team and the real world. Good documentation saves time, money, and frustration. When answering exam questions, always start by identifying the audience—is it a programmer or a customer? This will tell you which components are relevant.