Quality Assurance Measures and Documentation Types

This article is a glossary entry on documentation as a QA tool, complete with exam questions and tags.

In a Nutshell

Documentation makes requirements, behaviour, and evidence auditable. Core artefacts: user documentation, API documentation, program documentation, network documentation, test reports, and checklists—each with clear objectives, structure, ownership, and maintenance processes.

Technical Overview

User Documentation

Targets end users and operations: tasks, step-by-step workflows, error scenarios, support channels. Goal: enable self-service, reduce support burden.

API Documentation

Defines contracts: endpoints, data schemas, error codes, authentication, versioning. Foundation for interoperability and contract testing.

Program Documentation

Focuses on maintainable implementation: architecture overview, modules, public interfaces, invariants, code comments, build and runbook instructions.

Network Documentation

Describes topology, security zones, ports, protocols, traffic flows, and access controls. Essential for hardening and troubleshooting.

Test Reports

Demonstrate test effectiveness: traceability to test plans, environment details, test cases, actual results, defects, and release approvals.

Checklists

Standardise recurring inspections (code reviews, go-live gates, onboarding). Prevent oversights.

For compliance purposes, the traceable link matters most: requirement → evidence → outcome, connected through tickets, commits, builds, and releases.

Exam-Relevant Points

• Target audience and purpose clearly defined for each document
• Versioning, change tracking, ownership, and review cycles
• Minimum content per type (use templates)
• Evidence function (acceptance, audit, support, operations)
• Quality: current, complete, unambiguous, testable, understandable
• Integration with QA (requirement ↔ test case ↔ result ↔ defect ↔ release)
• Tools: wikis, Markdown repositories, diagrams-as-code, ticket linking
• Professional qualification relevance: demonstrate documentation is maintained, versioned, linked, and embedded in process

Core Components

1. User documentation (audience, tasks, workflows, examples, error handling, support)
2. API documentation (purpose, endpoints, methods, schemas, errors, authentication, versioning)
3. Program documentation (architecture, modules, public interfaces, data models, invariants, build/run)
4. Network documentation (topology, IP ranges, security zones, ports/protocols, firewall rules, traffic flows, high availability)
5. Test report (test plan reference, environment, test cases, actual results, defects, approvals)
6. Checklist (purpose, check items, evidence, owners, date, result, deviations)
7. Governance (owner, review cycle, changelog, release levels)
8. Storage (single source of truth, access control, discoverability, versioning in repository)
9. Quality (readability review, consistency checks, staleness tracking, link verification)
10. Compliance (ISO 25010 alignment, data protection, security, operations)

Practical Example (Shopping Cart API + Admin Portal)

User documentation:
- Audience: order processing staff, administrators
- Tasks: enter order, issue credit note
- Workflow: start → login → search customer → add items → check discount → complete order
- Error handling: common error messages with solutions
- Support: contact hours, ticket process

API documentation:
- OpenAPI: POST /api/orders, GET /api/orders/{id}
- Schemas: Order, OrderItem (with constraints)
- Errors: 400 validation, 401 authentication, 409 conflict
- Authentication: OAuth2, scopes order:write, order:read
- Versioning: Accept: application/vnd.shop.v1+json + deprecation plan

Program documentation:
- Architecture: layered design, Controller → Service → Repository, ports & adapters
- Key classes: OrderService, invariant: total amount ≥ 0
- Configuration: profiles, secrets via Vault
- Build: tooling, startup commands, logging, tracing

Network documentation:
- Zones: Internet → DMZ → App → Database
- Flows: browser → portal (TLS 443) → API (TLS 443) → database (5432)
- Firewall: baseline rules, monitoring points
- High availability: reverse proxy, 2 instances, database replica

Test report:
- Test plan reference: TP-007, environment: staging-23
- Cases: order with discount, boundary values, error paths
- Results: passed, passed, failed → defect ID 532
- Approval: product owner confirmed, date, signature

Checklists:
- Code review: architecture sound, security considered, tests passing, docs updated
- Go-live: monitoring active, runbooks complete, rollback plan in place, feature flags staged

Pros and Cons

Pros

• Traceability and auditability
• Faster onboarding
• Lower operational and support costs
• Compliance-ready

Cons

• Maintenance overhead
• Risk of outdated content
• Discipline and clear ownership required

Typical Exam Questions (with Brief Answers)

1. Why is API documentation critical for QA? It defines testable contracts, enables contract testing, and prevents integration failures.

2. What must user documentation include at minimum? Target audiences, tasks, step-by-step workflows, examples, error guidance, support channels, version information.

3. How does program documentation improve maintainability? It describes architecture, modules, public interfaces, and invariants, reducing onboarding time and change risk.

4. What should a test report contain? Test plan references, environment details, test cases, actual results, identified defects, approvals, date, and owners.

5. When are checklists most useful? For repetitive activities with risk: code reviews, release gates, and onboarding procedures.

Key Sources

1. https://iso25000.com
2. https://www.w3.org/TR/using-aria (for semantic UI documentation)
3. https://plantuml.com