Introduction: Welcome to Documentation and Evaluation!
Welcome to one of the most vital stages of the Software Development Life Cycle (SDLC) in your A2 2 Application Development unit! Think about buying a brand-new, high-tech gadget. If it comes without an instruction manual, you will struggle to use it. And if the engineers who built it left no blueprints, no one will ever be able to fix or upgrade it if something breaks.
In this chapter, you will discover why a software project is never truly finished just because the code runs. You will learn about two essential types of documentation—User Documentation and Technical Documentation—and how to conduct a thorough, critical Evaluation of a software solution. Don't worry if this seems a bit formal at first; we will break down every concept step-by-step with real-world analogies!
Section 1: User Documentation
What is User Documentation?
User Documentation (often called the User Guide or User Manual) is designed specifically for the end-user—the non-technical person who will actually operate the software on a day-to-day basis.
Analogy: Think of user documentation like the handbook inside a car's glove compartment. It tells the driver how to turn on the headlights, adjust the seats, pair their phone via Bluetooth, and what that flashing warning light on the dashboard means. It does not explain how the fuel-injection algorithm works under the hood!
Key Contents of User Documentation
A comprehensive user manual typically includes the following components:
• System Requirements: The minimum hardware (e.g. RAM, storage space, processor speed) and software (e.g. Operating System version) needed to run the program properly.
• Installation Instructions: Clear, step-by-step instructions guiding the user through downloading, installing, and setting up the software on their machine.
• Getting Started / Navigation Guide: An overview of the user interface (UI), showing how to log in, navigate menus, and understand toolbars and buttons.
• Step-by-Step Task Tutorials: Clear walkthroughs showing how to perform common business tasks (for example: "How to add a new customer record" or "How to generate a monthly sales report"), often illustrated with annotated screenshots.
• Troubleshooting Guide and FAQs: Answers to common questions and solutions to everyday errors (e.g. "What should I do if my password is rejected?" or "Why is the print button greyed out?").
• Glossary of Terms: Definitions of technical or business-specific jargon explained in plain, simple English.
• Contact and Support Details: Helpdesk phone numbers, support email addresses, or links to an online ticketing portal.
Format of Delivery
User documentation can be delivered in two primary formats:
1. Printed / PDF Manuals: Traditional booklets or downloadable guides that users can read offline.
2. On-screen / Integrated Help: Built-in help menus, interactive tutorials, tooltips (small pop-up explanations when hovering over icons), and searchable online knowledge bases.
Quick Review & Key Takeaway: User documentation is strictly for the end-user. Its primary purpose is to help someone install, operate, and troubleshoot the program without needing a computer science degree.
Section 2: Technical Documentation
What is Technical Documentation?
Technical Documentation (also known as Systems Documentation or Maintenance Documentation) is created for programmers, systems analysts, and network technicians. Its purpose is to explain the inner workings of the software so that future developers can maintain, repair, update, or extend the system.
Analogy: While user documentation is the car driver's handbook, technical documentation is the mechanic's full workshop blueprint and electrical wiring diagram!
Key Contents of Technical Documentation
Technical documentation contains detailed, low-level technical information about the system's architecture and design:
• System Architecture and Environment: Specific details regarding the development platform, programming languages used, database management system (DBMS), and network protocols.
• Data Structures and Data Dictionaries: Detailed tables listing every variable, array, record, and database table. A data dictionary specifies table names, field names, data types, field lengths, primary/foreign keys, and validation rules.
• Design Diagrams: Visual representations of the system, including Entity Relationship Diagrams (ERDs) showing database structures, Data Flow Diagrams (DFDs), and System Flowcharts.
• Annotated Source Code: The program code itself, featuring extensive internal documentation (meaningful variable names, modular subroutine structures, and explanatory code comments explaining complex logic).
• Algorithms and Logic: Flowcharts or pseudocode detailing the exact logic behind core calculations, sorting routines, or automated data processing functions.
• Validation Rules and Error Handling: A full breakdown of the validation checks implemented (e.g. range checks, presence checks, format checks) and how runtime errors are captured and handled.
• Test Plans and Test Results: A comprehensive record of all test cases used during development (testing normal, boundary, and erroneous data), showing the actual results achieved and any patches applied.
• Known Limitations and Bugs: Any identified issues or bottlenecks that were not resolved in the current build, giving future developers a head start.
Comparing User and Technical Documentation
• Target Audience: End-user / Client vs. Programmer / Systems Analyst.
• Purpose: How to use the software vs. How to maintain/fix/upgrade the software.
• Language Style: Non-technical, step-by-step, simple vs. Highly technical, precise, code-level.
• Core Components: Screenshots, FAQs, tutorials vs. Code listings, data dictionaries, ERDs, algorithms.
Quick Review & Key Takeaway: Without technical documentation, maintaining a legacy software system is almost impossible. It ensures that if the original developer leaves the company, another programmer can step in and understand the system quickly.
Section 3: Evaluation of the Software Solution
Why is Evaluation Essential?
Once a system has been designed, coded, tested, and documented, the developer must step back and critically judge how successful the project has been. Evaluation is an objective assessment of the final application against the original requirements identified during the initial analysis stage.
Core Criteria for a Comprehensive Evaluation
1. Evaluation Against User Requirements / Objectives
The developer must review each specific objective set out in the original project specification. For every requirement, ask:
• Did the solution meet this requirement in full, in part, or not at all?
• What evidence from testing demonstrates that this objective works successfully?
Example: If Requirement 1 was "The system must automatically calculate VAT at \(20\%\) and add it to the final invoice", the evaluation must confirm whether this calculation functions accurately under all tested conditions.
2. Performance, Efficiency, and Robustness
• Performance & Speed: Does the system respond promptly when querying the database or generating complex reports, even with large datasets?
• Efficiency: Does the software make good use of system memory and processing power without causing lag or freezing?
• Robustness & Reliability: How well does the system handle unexpected user actions or erroneous data? Does it display helpful error messages, or does it crash?
3. Usability and User Interface (UI/UX)
• Is the interface intuitive and clean?
• Are navigation menus consistent across all screens?
• Are font choices, colour schemes, and button placements accessible and user-friendly for all intended operators?
4. Limitations of the Current Solution
No software is 100% perfect. A strong evaluation honestly identifies what the system cannot do. For example:
• The system might only operate on a local standalone PC rather than over a network or cloud infrastructure.
• The system might only support single-user access rather than simultaneous multi-user transactions.
• Certain manual inputs might still be required where automated barcode scanning would have been better.
5. Opportunities for Future Enhancements
Based on the identified limitations and user feedback, the developer outlines realistic future developments. For instance:
• Upgrading the system to a web-based or mobile-friendly application.
• Integrating automated email notifications or SMS text alerts for customers.
• Adding advanced analytics dashboards and predictive sales forecasting.
Quick Review & Key Takeaway: A great evaluation is critical and balanced. It celebrates what works well by linking back to initial objectives, but also honestly identifies weaknesses, bottlenecks, and realistic future improvements.
Section 4: Memory Aids, Common Pitfalls & Exam Success
Memory Aid: The "U-T-E" Checklist
When revising this unit, remember the U-T-E framework:
• U - User Docs: Focus on How-To, FAQs, and clear screenshots for the everyday operator.
• T - Technical Docs: Focus on How it's Built, data dictionaries, algorithms, and annotated code for programmers.
• E - Evaluation: Focus on How Well it Works, matching outcomes to original objectives, identifying limitations, and planning future upgrades.
Common Pitfalls to Avoid in the Exam
• Confusing the Audiences: Never suggest putting annotated source code or database schemas into a User Guide. End-users do not need to see code!
• Vague Evaluation Statements: Avoid writing empty claims like "The program works brilliantly and has no errors." Always justify your evaluation by referencing specific user requirements, test evidence, and actual performance metrics.
• Ignoring Limitations: Examiners award top marks to candidates who can critically identify what their application lacks and provide sensible, realistic recommendations for future versions.