System Design (LLD)LLD Problem-Solving Framework

Gathering Requirements

LevelIntermediate

Duration90 mins

TopicLLD Problem-Solving Framework

4 / 4

Documenting Requirements

From Conversations to Contracts

Requirements that exist only in your head—or scattered across chats, emails, and meeting notes—are requirements that will be forgotten, misunderstood, or contradicted. Documentation transforms fleeting understanding into durable artifacts that guide design, resolve disputes, and enable team collaboration.

In Low-Level Design, requirement documentation serves critical purposes:

Drives design decisions — Each requirement should trace to specific design elements
Resolves ambiguity — Written requirements force precision that conversation lacks
Enables validation — Clear requirements can be verified against the final design
Supports communication — Teams align around shared documentation
Provides audit trail — Changes to requirements are tracked and explained

This page will equip you with professional-grade documentation techniques used by principal engineers and architects at world-class organizations.

What You Will Learn

By completing this page, you will master: • Structured formats for documenting functional and non-functional requirements • Techniques for ensuring completeness and avoiding gaps • How to organize requirements for different audiences • Traceability practices connecting requirements to design elements • Version control and change management for requirements • Practical templates you can apply immediately

Why Document Requirements?

Before diving into formats and templates, let's understand why documentation matters—and when it doesn't.

When Documentation Is Essential

Documentation Is Critical When...

•Multiple people are involved — Documentation creates shared understanding across team members
•Requirements are complex — Complex logic benefits from written specification
•Decisions must be justified — Stakeholders or auditors may ask why certain choices were made
•Work spans time — Requirements you understand today may be forgotten next month
•Handoffs occur — New team members need context without verbal history
•Compliance matters — Regulated industries require documented requirements

In LLD Interviews

In interviews, documentation happens in real-time—often on a whiteboard or shared document. The principles still apply:

Interview Documentation Practices

•Write down clarified requirements before designing—shows discipline
•List assumptions explicitly — interviewer can correct misunderstandings
•Organize visually — use columns, sections, bullets for clarity
•Reference requirements during design — 'This class addresses FR-003'

The Interview Edge

Candidates who document requirements before designing demonstrate maturity that distinguishes them from candidates who dive straight into code. Even in time-constrained interviews, spending 2-3 minutes writing down requirements pays dividends in design quality and communication clarity.

Core Documentation Components

A complete requirements document contains several interconnected sections that together provide a comprehensive picture.

Standard Document Structure

Requirements Document Structure
Section	Purpose	Key Contents
1. Overview	Set context and scope	System purpose, goals, high-level description, out-of-scope items
2. Actors/Users	Define who uses the system	User types, roles, permissions, external systems
3. Functional Requirements	Define what system does	Use cases, operations, business rules, workflows
4. Non-Functional Requirements	Define quality attributes	Performance, reliability, security, scalability, maintainability
5. Data Requirements	Define information needs	Entities, attributes, relationships, volumes, lifecycle
6. Constraints	Define limitations	Technical, business, regulatory, integration constraints
7. Assumptions	Document unstated premises	Things assumed true but not explicitly confirmed
8. Glossary	Define terminology	Domain-specific terms, abbreviations, ambiguous words

Adapting for LLD Context

For Low-Level Design specifically, we emphasize certain sections more than others:

LLD-Focused Documentation Priorities

•Actors and their operations — Who does what? This drives class design.
•Core entities and relationships — What data exists? This drives domain model.
•Business rules and constraints — What logic applies? This drives validation and policies.
•State transitions — How do entities change? This drives state machines.
•Edge cases and error scenarios — What can go wrong? This drives exception handling.

Documenting Functional Requirements

Functional requirements should be documented with enough detail to drive implementation decisions. Several formats exist, each with trade-offs.

Simple List Format

The most basic format—suitable for quick documentation:

Simple List Format
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
## Functional Requirements
 
### Book Management
- FR-001: Librarians can add new books to the catalog
- FR-002: Librarians can update existing book information
- FR-003: Librarians can remove books from the catalog
- FR-004: System generates unique ISBN-based identifiers for each book
 
### Member Operations
- FR-005: Members can search books by title, author, or ISBN
- FR-006: Members can borrow available books (max 5 at a time)
- FR-007: Members can return borrowed books
- FR-008: Members can reserve books currently borrowed by others
- FR-009: Members can view their borrowing history
 
### System Automation
- FR-010: System sends notifications 3 days before due date
- FR-011: System sends overdue notifications daily until return
- FR-012: System calculates and applies late fees automatically

Structured Requirement Format

For more complex requirements, use a structured template:

Structured Requirement Template
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
## FR-006: Borrow Book
 
### Description
Members can borrow books that are currently available in the library.
 
### Actor
Member (authenticated)
 
### Preconditions
- Member is logged in
- Member has not exceeded borrowing limit (5 books)
- Member has no overdue books
- Target book exists and is available
 
### Main Flow
1. Member selects a book to borrow
2. System validates member eligibility
3. System validates book availability
4. System creates borrowing record with 14-day due date
5. System updates book status to "Borrowed"
6. System confirms successful borrowing to member
 
### Alternative Flows
- **4a. Book unavailable:** Offer to place reservation instead
- **3a. Member at limit:** Display current borrowings and limit
- **2a. Member has overdue:** Require return before new borrowing
 
### Postconditions
- Borrowing record created (member, book, borrow date, due date)
- Book status changed to "Borrowed"
- Member's borrowed count incremented
- Audit log entry created
 
### Business Rules
- Due date = borrow date + 14 days
- Only physical books can be borrowed (not reference-only)
- VIP members have limit of 10 books instead of 5
 
### Priority
High (core functionality)

Use Case Format

For complex interactions, the use case format provides comprehensive coverage:

Use Case Template Fields
Field	Description	Example
Use Case ID	Unique identifier	UC-006
Use Case Name	Descriptive title	Borrow Book
Primary Actor	Who initiates	Library Member
Secondary Actors	Other participants	Notification Service
Trigger	What starts it	Member clicks 'Borrow' on book detail
Preconditions	Required state before	Member logged in, book available
Main Success Scenario	Happy path steps	Numbered flow
Extensions	Alternative/error paths	Branching scenarios
Postconditions	Required state after	Book borrowed, record created
Business Rules	Domain constraints	Max 5 books per member

Documenting Non-Functional Requirements

Non-functional requirements need quantifiable metrics and clear measurement criteria to be useful.

NFR Documentation Template

NFR Documentation Template
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
## NFR-001: Search Performance
 
### Category
Performance
 
### Requirement Statement
Book search queries must return results within 200 milliseconds at the 
95th percentile under normal operating conditions.
 
### Metric
- **Measurement:** Response time from API request to response
- **Target:** ≤ 200ms at 95th percentile
- **Threshold:** ≤ 500ms at 99th percentile (alert if exceeded)
 
### Conditions
- Normal load: up to 500 concurrent users
- Catalog size: up to 1 million books
- Query type: title, author, or ISBN search
 
### Rationale
User studies show abandonment increases significantly when search 
exceeds 1 second. 200ms provides responsive feel with margin for 
network latency.
 
### Verification Method
1. Load testing with representative query patterns
2. Production monitoring with percentile dashboards
3. Automated alerting when threshold exceeded
 
### Design Implications
- Requires search index (database queries alone may be too slow)
- May need caching layer for popular queries
- Consider pagination to limit result set size
 
### Priority
High
 
### Related Requirements
- FR-005: Book search functionality
- NFR-005: Scalability - catalog size growth

NFR Category Checklist

Ensure you've addressed all relevant NFR categories:

NFR Coverage Checklist
Category	Key Questions	Document If...
Performance	Response time? Throughput? Resource limits?	Customer-facing or high-volume operations
Reliability	Failure tolerance? Data integrity? Recovery?	Critical data or operations
Availability	Uptime target? Maintenance windows?	Business has availability SLAs
Security	Authentication? Authorization? Encryption? Audit?	Sensitive data or operations
Scalability	Growth expectations? Peak load patterns?	Expected significant growth
Maintainability	Modification ease? Debugging support?	Frequent changes expected
Compliance	Regulations? Standards? Audit requirements?	Regulated industry

Documenting Data Requirements

For LLD, data requirements directly inform your class design. Document entities, their attributes, and relationships.

Entity Catalog

List all significant entities with their essential attributes:

Entity Catalog Example
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
## Data Entities
 
### Book
| Attribute       | Type           | Constraints                    |
|-----------------|----------------|--------------------------------|
| id              | UUID           | Primary key, auto-generated    |
| isbn            | String         | Unique, 13 characters          |
| title           | String         | Required, max 500 chars        |
| author          | String         | Required, max 200 chars        |
| publisher       | String         | Optional                       |
| publicationYear | Integer        | 1450-current year              |
| category        | Enum           | FICTION, NON_FICTION, etc.     |
| status          | Enum           | AVAILABLE, BORROWED, RESERVED  |
| addedDate       | Timestamp      | Auto-set on creation           |
 
### Member
| Attribute       | Type           | Constraints                    |
|-----------------|----------------|--------------------------------|
| id              | UUID           | Primary key                    |
| email           | String         | Unique, valid email format     |
| name            | String         | Required                       |
| membershipType  | Enum           | STANDARD, VIP                  |
| joinDate        | Date           | Required                       |
| status          | Enum           | ACTIVE, SUSPENDED              |
 
### Borrowing
| Attribute       | Type           | Constraints                    |
|-----------------|----------------|--------------------------------|
| id              | UUID           | Primary key                    |
| memberId        | UUID           | FK to Member                   |
| bookId          | UUID           | FK to Book                     |
| borrowDate      | Date           | Required                       |
| dueDate         | Date           | borrowDate + 14 days           |
| returnDate      | Date           | Null if not returned           |
| status          | Enum           | ACTIVE, RETURNED, OVERDUE      |

Relationship Documentation

Document relationships between entities:

Relationship Documentation
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
## Entity Relationships
 
### Member → Borrowing (One-to-Many)
- One member can have multiple active borrowings
- Maximum: 5 for STANDARD, 10 for VIP
- Navigable from Member to their borrowings
- Cascade: Member deletion → archive borrowings (don't delete)
 
### Book → Borrowing (One-to-Many)
- One book has one active borrowing at a time
- Historical borrowings retained for audit
- Navigable from Book to current/past borrowings
- Cascade: Book deletion → soft delete borrowings
 
### Member → Reservation (One-to-Many)
- Member can have multiple pending reservations
- Maximum: 3 active reservations per member
- Navigable both directions
 
### Book → Reservation (One-to-Many)
- Book can have multiple queued reservations
- Order by reservation timestamp (FIFO)
- Navigable from Book to reservation queue

From Data to Classes

Data requirements directly become classes: • Entities → Domain classes (Book, Member, Borrowing) • Attributes → Instance fields with appropriate types • Constraints → Validation logic and constructors • Relationships → References and collection fields • Status fields → Enums and state machines

Documenting Edge Cases and Business Rules

Edge cases and business rules often determine design complexity. Document them explicitly rather than discovering them during implementation.

Business Rules Catalog

Business Rules Catalog
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
## Business Rules
 
### BR-001: Borrowing Limits
- Standard members: maximum 5 concurrent borrowings
- VIP members: maximum 10 concurrent borrowings
- Applies to active (non-returned) borrowings only
 
### BR-002: Borrowing Duration
- Standard lending period: 14 days
- Reference books: 7 days, no renewal
- New arrivals (first 30 days): 7 days, 1 renewal only
 
### BR-003: Renewal Policy
- Renewals extend due date by 14 days from renewal date
- Maximum 2 renewals per borrowing
- Cannot renew if: book has pending reservations
- Cannot renew if: book is overdue
 
### BR-004: Late Fees
- $0.25 per day overdue per book
- Maximum fee per book: purchase price of book
- Fees accrue daily at midnight
- Outstanding fees > $10 suspend borrowing privileges
 
### BR-005: Reservation Priority
- Reservations filled in FIFO order
- Reservation expires if not picked up within 3 days of availability
- Expired reservation releases book to next in queue
- Member notified via email when reserved book becomes available
 
### BR-006: Concurrent Borrowing Prevention
- Only one active borrowing per book at any time
- If two members try to borrow simultaneously, first to complete wins
- Loser receives reservation offer

Edge Case Documentation

Edge Cases Document
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
## Edge Cases
 
### EC-001: Simultaneous Borrow Attempts
**Scenario:** Two members click "Borrow" on the same book within milliseconds
**Handling:** Use pessimistic locking on book status check
**Expected Behavior:** First transaction commits, second receives "unavailable" message
**Design Impact:** BorrowingService must use @Transactional with SERIALIZABLE isolation
 
### EC-002: Book Removed While Borrowed
**Scenario:** Librarian removes book from catalog while member has it borrowed
**Handling:** Soft delete only; book remains in system as "REMOVED"
**Expected Behavior:** Member can still return; no new borrowings allowed
**Design Impact:** Book.delete() is soft delete; status changes to REMOVED
 
### EC-003: Member Account Suspended Mid-Borrow
**Scenario:** Member suspended for overdue fees while holding books
**Handling:** Existing borrowings remain active; no new borrowings allowed
**Expected Behavior:** Return still works; notifications emphasize return urgency
**Design Impact:** Suspension check only on new borrow operations
 
### EC-004: Reservation Cascade on Extended Borrow
**Scenario:** Member renews book that has pending reservations
**Handling:** Renewal blocked per BR-003
**Expected Behavior:** User informed reservation exists; suggest returning
**Design Impact:** RenewalPolicy checks reservation queue
 
### EC-005: Payment System Unavailable
**Scenario:** Fine payment attempted but payment service down
**Handling:** Graceful degradation; record pending payment
**Expected Behavior:** User informed of issue; can retry; browsing still works
**Design Impact:** PaymentService has fallback mode; FinePayment has PENDING state

Traceability and Cross-References

Traceability connects requirements to design elements to tests. This ensures nothing is missed and facilitates impact analysis when requirements change.

Traceability Matrix

A traceability matrix links requirements to implementation:

Requirements Traceability Matrix (Sample)
Requirement	Design Element	Class/Method	Test Cases
FR-005: Search books	BookSearchService	searchByTitle(), searchByAuthor(), searchByISBN()	TC-101 through TC-115
FR-006: Borrow book	BorrowingService	borrowBook(memberId, bookId)	TC-201 through TC-220
BR-001: Borrow limits	BorrowingPolicy	canBorrow(member)	TC-301 through TC-308
NFR-001: Search perf	SearchIndex	BookSearchIndex with HashMap	PT-001, PT-002

Cross-Reference Notation

Use consistent ID prefixes for easy reference:

Standard ID Prefixes
Prefix	Type	Example
FR-	Functional Requirement	FR-006
NFR-	Non-Functional Requirement	NFR-001
BR-	Business Rule	BR-003
EC-	Edge Case	EC-002
UC-	Use Case	UC-006
ENT-	Entity	ENT-Book
TC-	Test Case	TC-201

Traceability in Interviews

In interviews, you won't create formal traceability matrices. However, verbally referencing requirements during design demonstrates the same thinking:

"This BorrowingPolicy class specifically addresses BR-001, the borrowing limits rule. The canBorrow method checks member type and current borrowing count."

This shows you're designing against requirements, not ad-hoc.

Living Documentation Practices

Requirements evolve. Static documents that aren't updated become misleading and eventually ignored. Professional requirement management treats documentation as living artifacts.

Version Control for Requirements

Track requirement changes like code changes:

Requirement Change History

Markdown

## Change History
 
| Version | Date       | Author      | Changes                              |
|---------|------------|-------------|--------------------------------------|
| 1.0     | 2024-01-15 | J. Smith    | Initial requirements baseline        |
| 1.1     | 2024-02-03 | A. Johnson  | Added VIP member limits (BR-001)     |
| 1.2     | 2024-02-20 | J. Smith    | Added NFR-003 security requirements  |
| 1.3     | 2024-03-05 | A. Johnson  | Modified late fee calculation (BR-004)|
 
## Pending Changes
 
| ID     | Description                          | Status    | Target   |
|--------|--------------------------------------|-----------|----------|
| CHG-01 | Add digital book borrowing           | Proposed  | v2.0     |
| CHG-02 | Increase VIP limit to 15             | Approved  | v1.4     |
| CHG-03 | Add payment plan for large fines     | Under review | -     |

Assumption Tracking

Explicitly documented assumptions become requirements when validated:

Assumption Log

Markdown

## Assumptions
 
| ID     | Assumption                                   | Status      | Notes                    |
|--------|----------------------------------------------|-------------|--------------------------|
| ASM-01 | Single library location                      | Confirmed   | Multi-branch for v2.0    |
| ASM-02 | Physical books only                          | Confirmed   | E-books planned          |
| ASM-03 | Borrowing limit 5 standard, 10 VIP           | Confirmed   | Now in BR-001            |
| ASM-04 | No holds on reference materials              | Unconfirmed | Awaiting librarian input |
| ASM-05 | Email is primary notification channel        | Confirmed   | SMS for urgent only      |
 
## Unknowns / Open Questions
 
| ID     | Question                                     | Owner       | Due        |
|--------|----------------------------------------------|-------------|------------|
| UNK-01 | Integration with city payment system?        | Tech Lead   | 2024-03-15 |
| UNK-02 | Historical data migration requirements?      | PM          | 2024-03-10 |

Documentation as Communication

Good documentation serves as an asynchronous communication channel. Team members can understand decisions without needing to interrupt you. Stakeholders can review progress without meetings. New joiners can ramp up without extensive knowledge transfer sessions.

Invest time in documentation, and it returns time many-fold.

Quick Reference Templates

Here are condensed templates you can use immediately for requirement documentation.

Interview Quick Template

Use this during LLD interviews to capture requirements efficiently:

Interview Requirements Template
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
## [System Name] Requirements
 
### Scope & Actors
- Primary actors: 
- Secondary actors:
- In scope: 
- Out of scope:
 
### Core Functional Requirements
1. [Actor] can [action] [object]
2. 
3. 
 
### Key Business Rules
- BR-1: 
- BR-2:
 
### Non-Functional Considerations
- Scale: [users, data volume]
- Performance: [critical operations]
- Security: [auth, sensitive data]
 
### Key Assumptions
1. 
2. 
 
### Questions Answered
- Q: ... A: ...

Complete Project Template

For thorough project documentation:

Complete Requirements Document Template
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
# [System Name] Requirements Specification
 
## 1. Document Info
- **Version:** 1.0
- **Last Updated:** [Date]
- **Author:** [Name]
- **Status:** Draft / Under Review / Approved
 
## 2. Overview
### 2.1 Purpose
[What problem does this system solve?]
 
### 2.2 Scope
[What's included and excluded]
 
### 2.3 Stakeholders
[Who cares about this system]
 
## 3. Actors & Roles
[Table of actor types with descriptions and permissions]
 
## 4. Functional Requirements
### 4.1 [Feature Area 1]
- FR-001: [Requirement]
- FR-002: [Requirement]
 
### 4.2 [Feature Area 2]
...
 
## 5. Non-Functional Requirements
### 5.1 Performance
- NFR-001: [Metric-based requirement]
 
### 5.2 Security
...
 
### 5.3 Reliability
...
 
## 6. Data Requirements
### 6.1 Entity Catalog
[Entity tables with attributes]
 
### 6.2 Relationships
[Relationship descriptions]
 
## 7. Business Rules
- BR-001: [Rule with conditions and actions]
 
## 8. Constraints
[Technical, business, regulatory limitations]
 
## 9. Assumptions
[Things assumed true]
 
## 10. Glossary
[Term definitions]
 
## Appendix: Change History
[Version log]

Summary: Mastering Requirement Documentation

Documentation transforms ephemeral understanding into durable knowledge. Well-documented requirements guide design, enable validation, and support collaboration.

Key Takeaways

•Document to drive design — Each requirement should trace to design elements.
•Use structured formats — Templates ensure completeness and consistency.
•Quantify NFRs — Vague quality requirements aren't actionable.
•Document data explicitly — Entity catalogs become class designs.
•Capture business rules — These drive validation and policy logic.
•Document edge cases — Edge cases reveal design complexity.
•Maintain traceability — Connect requirements to implementation to tests.
•Keep documentation living — Track changes, assumptions, and open questions.
•Adapt depth to context — Interview quick templates vs. full project specs.

Module Complete!

You've now mastered the complete requirement gathering process:

Functional Requirements — What the system must do
Non-Functional Requirements — How well it must perform
Clarifying Questions — Extracting complete information
Documentation — Capturing requirements durably

With requirements firmly in hand, you're ready for the next phase of LLD: identifying the core entities that will become your classes and objects. Entities emerge directly from well-gathered requirements.

Module Complete

Congratulations! You now possess world-class requirement gathering skills. You can extract, analyze, document, and trace requirements with the rigor expected of principal engineers. This foundation ensures every design you create is built on solid understanding rather than assumptions. The next module explores identifying core entities—translating requirements into the building blocks of your design.

4 / 4

Loading learning content...

System Design (LLD)LLD Problem-Solving Framework

Gathering Requirements

LevelIntermediate

Duration90 mins

TopicLLD Problem-Solving Framework

4 / 4

Documenting Requirements

From Conversations to Contracts

In Low-Level Design, requirement documentation serves critical purposes:

Drives design decisions — Each requirement should trace to specific design elements
Resolves ambiguity — Written requirements force precision that conversation lacks
Enables validation — Clear requirements can be verified against the final design
Supports communication — Teams align around shared documentation
Provides audit trail — Changes to requirements are tracked and explained

This page will equip you with professional-grade documentation techniques used by principal engineers and architects at world-class organizations.

What You Will Learn

Why Document Requirements?

Before diving into formats and templates, let's understand why documentation matters—and when it doesn't.

When Documentation Is Essential

Documentation Is Critical When...

•Multiple people are involved — Documentation creates shared understanding across team members
•Requirements are complex — Complex logic benefits from written specification
•Decisions must be justified — Stakeholders or auditors may ask why certain choices were made
•Work spans time — Requirements you understand today may be forgotten next month
•Handoffs occur — New team members need context without verbal history
•Compliance matters — Regulated industries require documented requirements

In LLD Interviews

In interviews, documentation happens in real-time—often on a whiteboard or shared document. The principles still apply:

Interview Documentation Practices

•Write down clarified requirements before designing—shows discipline
•List assumptions explicitly — interviewer can correct misunderstandings
•Organize visually — use columns, sections, bullets for clarity
•Reference requirements during design — 'This class addresses FR-003'

The Interview Edge

Core Documentation Components

A complete requirements document contains several interconnected sections that together provide a comprehensive picture.

Standard Document Structure

Requirements Document Structure
Section	Purpose	Key Contents
1. Overview	Set context and scope	System purpose, goals, high-level description, out-of-scope items
2. Actors/Users	Define who uses the system	User types, roles, permissions, external systems
3. Functional Requirements	Define what system does	Use cases, operations, business rules, workflows
4. Non-Functional Requirements	Define quality attributes	Performance, reliability, security, scalability, maintainability
5. Data Requirements	Define information needs	Entities, attributes, relationships, volumes, lifecycle
6. Constraints	Define limitations	Technical, business, regulatory, integration constraints
7. Assumptions	Document unstated premises	Things assumed true but not explicitly confirmed
8. Glossary	Define terminology	Domain-specific terms, abbreviations, ambiguous words

Adapting for LLD Context

For Low-Level Design specifically, we emphasize certain sections more than others:

LLD-Focused Documentation Priorities

•Actors and their operations — Who does what? This drives class design.
•Core entities and relationships — What data exists? This drives domain model.
•Business rules and constraints — What logic applies? This drives validation and policies.
•State transitions — How do entities change? This drives state machines.
•Edge cases and error scenarios — What can go wrong? This drives exception handling.

Documenting Functional Requirements

Functional requirements should be documented with enough detail to drive implementation decisions. Several formats exist, each with trade-offs.

Simple List Format

The most basic format—suitable for quick documentation:

Simple List Format
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
## Functional Requirements
 
### Book Management
- FR-001: Librarians can add new books to the catalog
- FR-002: Librarians can update existing book information
- FR-003: Librarians can remove books from the catalog
- FR-004: System generates unique ISBN-based identifiers for each book
 
### Member Operations
- FR-005: Members can search books by title, author, or ISBN
- FR-006: Members can borrow available books (max 5 at a time)
- FR-007: Members can return borrowed books
- FR-008: Members can reserve books currently borrowed by others
- FR-009: Members can view their borrowing history
 
### System Automation
- FR-010: System sends notifications 3 days before due date
- FR-011: System sends overdue notifications daily until return
- FR-012: System calculates and applies late fees automatically

Structured Requirement Format

For more complex requirements, use a structured template:

Structured Requirement Template
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
## FR-006: Borrow Book
 
### Description
Members can borrow books that are currently available in the library.
 
### Actor
Member (authenticated)
 
### Preconditions
- Member is logged in
- Member has not exceeded borrowing limit (5 books)
- Member has no overdue books
- Target book exists and is available
 
### Main Flow
1. Member selects a book to borrow
2. System validates member eligibility
3. System validates book availability
4. System creates borrowing record with 14-day due date
5. System updates book status to "Borrowed"
6. System confirms successful borrowing to member
 
### Alternative Flows
- **4a. Book unavailable:** Offer to place reservation instead
- **3a. Member at limit:** Display current borrowings and limit
- **2a. Member has overdue:** Require return before new borrowing
 
### Postconditions
- Borrowing record created (member, book, borrow date, due date)
- Book status changed to "Borrowed"
- Member's borrowed count incremented
- Audit log entry created
 
### Business Rules
- Due date = borrow date + 14 days
- Only physical books can be borrowed (not reference-only)
- VIP members have limit of 10 books instead of 5
 
### Priority
High (core functionality)

Use Case Format

For complex interactions, the use case format provides comprehensive coverage:

Use Case Template Fields
Field	Description	Example
Use Case ID	Unique identifier	UC-006
Use Case Name	Descriptive title	Borrow Book
Primary Actor	Who initiates	Library Member
Secondary Actors	Other participants	Notification Service
Trigger	What starts it	Member clicks 'Borrow' on book detail
Preconditions	Required state before	Member logged in, book available
Main Success Scenario	Happy path steps	Numbered flow
Extensions	Alternative/error paths	Branching scenarios
Postconditions	Required state after	Book borrowed, record created
Business Rules	Domain constraints	Max 5 books per member

Documenting Non-Functional Requirements

Non-functional requirements need quantifiable metrics and clear measurement criteria to be useful.

NFR Documentation Template

NFR Documentation Template
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
## NFR-001: Search Performance
 
### Category
Performance
 
### Requirement Statement
Book search queries must return results within 200 milliseconds at the 
95th percentile under normal operating conditions.
 
### Metric
- **Measurement:** Response time from API request to response
- **Target:** ≤ 200ms at 95th percentile
- **Threshold:** ≤ 500ms at 99th percentile (alert if exceeded)
 
### Conditions
- Normal load: up to 500 concurrent users
- Catalog size: up to 1 million books
- Query type: title, author, or ISBN search
 
### Rationale
User studies show abandonment increases significantly when search 
exceeds 1 second. 200ms provides responsive feel with margin for 
network latency.
 
### Verification Method
1. Load testing with representative query patterns
2. Production monitoring with percentile dashboards
3. Automated alerting when threshold exceeded
 
### Design Implications
- Requires search index (database queries alone may be too slow)
- May need caching layer for popular queries
- Consider pagination to limit result set size
 
### Priority
High
 
### Related Requirements
- FR-005: Book search functionality
- NFR-005: Scalability - catalog size growth

NFR Category Checklist

Ensure you've addressed all relevant NFR categories:

NFR Coverage Checklist
Category	Key Questions	Document If...
Performance	Response time? Throughput? Resource limits?	Customer-facing or high-volume operations
Reliability	Failure tolerance? Data integrity? Recovery?	Critical data or operations
Availability	Uptime target? Maintenance windows?	Business has availability SLAs
Security	Authentication? Authorization? Encryption? Audit?	Sensitive data or operations
Scalability	Growth expectations? Peak load patterns?	Expected significant growth
Maintainability	Modification ease? Debugging support?	Frequent changes expected
Compliance	Regulations? Standards? Audit requirements?	Regulated industry

Documenting Data Requirements

For LLD, data requirements directly inform your class design. Document entities, their attributes, and relationships.

Entity Catalog

List all significant entities with their essential attributes:

Entity Catalog Example
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
## Data Entities
 
### Book
| Attribute       | Type           | Constraints                    |
|-----------------|----------------|--------------------------------|
| id              | UUID           | Primary key, auto-generated    |
| isbn            | String         | Unique, 13 characters          |
| title           | String         | Required, max 500 chars        |
| author          | String         | Required, max 200 chars        |
| publisher       | String         | Optional                       |
| publicationYear | Integer        | 1450-current year              |
| category        | Enum           | FICTION, NON_FICTION, etc.     |
| status          | Enum           | AVAILABLE, BORROWED, RESERVED  |
| addedDate       | Timestamp      | Auto-set on creation           |
 
### Member
| Attribute       | Type           | Constraints                    |
|-----------------|----------------|--------------------------------|
| id              | UUID           | Primary key                    |
| email           | String         | Unique, valid email format     |
| name            | String         | Required                       |
| membershipType  | Enum           | STANDARD, VIP                  |
| joinDate        | Date           | Required                       |
| status          | Enum           | ACTIVE, SUSPENDED              |
 
### Borrowing
| Attribute       | Type           | Constraints                    |
|-----------------|----------------|--------------------------------|
| id              | UUID           | Primary key                    |
| memberId        | UUID           | FK to Member                   |
| bookId          | UUID           | FK to Book                     |
| borrowDate      | Date           | Required                       |
| dueDate         | Date           | borrowDate + 14 days           |
| returnDate      | Date           | Null if not returned           |
| status          | Enum           | ACTIVE, RETURNED, OVERDUE      |

Relationship Documentation

Document relationships between entities:

Relationship Documentation
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
## Entity Relationships
 
### Member → Borrowing (One-to-Many)
- One member can have multiple active borrowings
- Maximum: 5 for STANDARD, 10 for VIP
- Navigable from Member to their borrowings
- Cascade: Member deletion → archive borrowings (don't delete)
 
### Book → Borrowing (One-to-Many)
- One book has one active borrowing at a time
- Historical borrowings retained for audit
- Navigable from Book to current/past borrowings
- Cascade: Book deletion → soft delete borrowings
 
### Member → Reservation (One-to-Many)
- Member can have multiple pending reservations
- Maximum: 3 active reservations per member
- Navigable both directions
 
### Book → Reservation (One-to-Many)
- Book can have multiple queued reservations
- Order by reservation timestamp (FIFO)
- Navigable from Book to reservation queue

From Data to Classes

Documenting Edge Cases and Business Rules

Edge cases and business rules often determine design complexity. Document them explicitly rather than discovering them during implementation.

Business Rules Catalog

Business Rules Catalog
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
## Business Rules
 
### BR-001: Borrowing Limits
- Standard members: maximum 5 concurrent borrowings
- VIP members: maximum 10 concurrent borrowings
- Applies to active (non-returned) borrowings only
 
### BR-002: Borrowing Duration
- Standard lending period: 14 days
- Reference books: 7 days, no renewal
- New arrivals (first 30 days): 7 days, 1 renewal only
 
### BR-003: Renewal Policy
- Renewals extend due date by 14 days from renewal date
- Maximum 2 renewals per borrowing
- Cannot renew if: book has pending reservations
- Cannot renew if: book is overdue
 
### BR-004: Late Fees
- $0.25 per day overdue per book
- Maximum fee per book: purchase price of book
- Fees accrue daily at midnight
- Outstanding fees > $10 suspend borrowing privileges
 
### BR-005: Reservation Priority
- Reservations filled in FIFO order
- Reservation expires if not picked up within 3 days of availability
- Expired reservation releases book to next in queue
- Member notified via email when reserved book becomes available
 
### BR-006: Concurrent Borrowing Prevention
- Only one active borrowing per book at any time
- If two members try to borrow simultaneously, first to complete wins
- Loser receives reservation offer

Edge Case Documentation

Edge Cases Document
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
## Edge Cases
 
### EC-001: Simultaneous Borrow Attempts
**Scenario:** Two members click "Borrow" on the same book within milliseconds
**Handling:** Use pessimistic locking on book status check
**Expected Behavior:** First transaction commits, second receives "unavailable" message
**Design Impact:** BorrowingService must use @Transactional with SERIALIZABLE isolation
 
### EC-002: Book Removed While Borrowed
**Scenario:** Librarian removes book from catalog while member has it borrowed
**Handling:** Soft delete only; book remains in system as "REMOVED"
**Expected Behavior:** Member can still return; no new borrowings allowed
**Design Impact:** Book.delete() is soft delete; status changes to REMOVED
 
### EC-003: Member Account Suspended Mid-Borrow
**Scenario:** Member suspended for overdue fees while holding books
**Handling:** Existing borrowings remain active; no new borrowings allowed
**Expected Behavior:** Return still works; notifications emphasize return urgency
**Design Impact:** Suspension check only on new borrow operations
 
### EC-004: Reservation Cascade on Extended Borrow
**Scenario:** Member renews book that has pending reservations
**Handling:** Renewal blocked per BR-003
**Expected Behavior:** User informed reservation exists; suggest returning
**Design Impact:** RenewalPolicy checks reservation queue
 
### EC-005: Payment System Unavailable
**Scenario:** Fine payment attempted but payment service down
**Handling:** Graceful degradation; record pending payment
**Expected Behavior:** User informed of issue; can retry; browsing still works
**Design Impact:** PaymentService has fallback mode; FinePayment has PENDING state

Traceability and Cross-References

Traceability connects requirements to design elements to tests. This ensures nothing is missed and facilitates impact analysis when requirements change.

Traceability Matrix

A traceability matrix links requirements to implementation:

Requirements Traceability Matrix (Sample)
Requirement	Design Element	Class/Method	Test Cases
FR-005: Search books	BookSearchService	searchByTitle(), searchByAuthor(), searchByISBN()	TC-101 through TC-115
FR-006: Borrow book	BorrowingService	borrowBook(memberId, bookId)	TC-201 through TC-220
BR-001: Borrow limits	BorrowingPolicy	canBorrow(member)	TC-301 through TC-308
NFR-001: Search perf	SearchIndex	BookSearchIndex with HashMap	PT-001, PT-002

Cross-Reference Notation

Use consistent ID prefixes for easy reference:

Standard ID Prefixes
Prefix	Type	Example
FR-	Functional Requirement	FR-006
NFR-	Non-Functional Requirement	NFR-001
BR-	Business Rule	BR-003
EC-	Edge Case	EC-002
UC-	Use Case	UC-006
ENT-	Entity	ENT-Book
TC-	Test Case	TC-201

Traceability in Interviews

In interviews, you won't create formal traceability matrices. However, verbally referencing requirements during design demonstrates the same thinking:

"This BorrowingPolicy class specifically addresses BR-001, the borrowing limits rule. The canBorrow method checks member type and current borrowing count."

This shows you're designing against requirements, not ad-hoc.

Living Documentation Practices

Requirements evolve. Static documents that aren't updated become misleading and eventually ignored. Professional requirement management treats documentation as living artifacts.

Version Control for Requirements

Track requirement changes like code changes:

Requirement Change History

Markdown

## Change History
 
| Version | Date       | Author      | Changes                              |
|---------|------------|-------------|--------------------------------------|
| 1.0     | 2024-01-15 | J. Smith    | Initial requirements baseline        |
| 1.1     | 2024-02-03 | A. Johnson  | Added VIP member limits (BR-001)     |
| 1.2     | 2024-02-20 | J. Smith    | Added NFR-003 security requirements  |
| 1.3     | 2024-03-05 | A. Johnson  | Modified late fee calculation (BR-004)|
 
## Pending Changes
 
| ID     | Description                          | Status    | Target   |
|--------|--------------------------------------|-----------|----------|
| CHG-01 | Add digital book borrowing           | Proposed  | v2.0     |
| CHG-02 | Increase VIP limit to 15             | Approved  | v1.4     |
| CHG-03 | Add payment plan for large fines     | Under review | -     |

Assumption Tracking

Explicitly documented assumptions become requirements when validated:

Assumption Log

Markdown

## Assumptions
 
| ID     | Assumption                                   | Status      | Notes                    |
|--------|----------------------------------------------|-------------|--------------------------|
| ASM-01 | Single library location                      | Confirmed   | Multi-branch for v2.0    |
| ASM-02 | Physical books only                          | Confirmed   | E-books planned          |
| ASM-03 | Borrowing limit 5 standard, 10 VIP           | Confirmed   | Now in BR-001            |
| ASM-04 | No holds on reference materials              | Unconfirmed | Awaiting librarian input |
| ASM-05 | Email is primary notification channel        | Confirmed   | SMS for urgent only      |
 
## Unknowns / Open Questions
 
| ID     | Question                                     | Owner       | Due        |
|--------|----------------------------------------------|-------------|------------|
| UNK-01 | Integration with city payment system?        | Tech Lead   | 2024-03-15 |
| UNK-02 | Historical data migration requirements?      | PM          | 2024-03-10 |

Documentation as Communication

Invest time in documentation, and it returns time many-fold.

Quick Reference Templates

Here are condensed templates you can use immediately for requirement documentation.

Interview Quick Template

Use this during LLD interviews to capture requirements efficiently:

Interview Requirements Template
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
## [System Name] Requirements
 
### Scope & Actors
- Primary actors: 
- Secondary actors:
- In scope: 
- Out of scope:
 
### Core Functional Requirements
1. [Actor] can [action] [object]
2. 
3. 
 
### Key Business Rules
- BR-1: 
- BR-2:
 
### Non-Functional Considerations
- Scale: [users, data volume]
- Performance: [critical operations]
- Security: [auth, sensitive data]
 
### Key Assumptions
1. 
2. 
 
### Questions Answered
- Q: ... A: ...

Complete Project Template

For thorough project documentation:

Complete Requirements Document Template
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
# [System Name] Requirements Specification
 
## 1. Document Info
- **Version:** 1.0
- **Last Updated:** [Date]
- **Author:** [Name]
- **Status:** Draft / Under Review / Approved
 
## 2. Overview
### 2.1 Purpose
[What problem does this system solve?]
 
### 2.2 Scope
[What's included and excluded]
 
### 2.3 Stakeholders
[Who cares about this system]
 
## 3. Actors & Roles
[Table of actor types with descriptions and permissions]
 
## 4. Functional Requirements
### 4.1 [Feature Area 1]
- FR-001: [Requirement]
- FR-002: [Requirement]
 
### 4.2 [Feature Area 2]
...
 
## 5. Non-Functional Requirements
### 5.1 Performance
- NFR-001: [Metric-based requirement]
 
### 5.2 Security
...
 
### 5.3 Reliability
...
 
## 6. Data Requirements
### 6.1 Entity Catalog
[Entity tables with attributes]
 
### 6.2 Relationships
[Relationship descriptions]
 
## 7. Business Rules
- BR-001: [Rule with conditions and actions]
 
## 8. Constraints
[Technical, business, regulatory limitations]
 
## 9. Assumptions
[Things assumed true]
 
## 10. Glossary
[Term definitions]
 
## Appendix: Change History
[Version log]

Summary: Mastering Requirement Documentation

Documentation transforms ephemeral understanding into durable knowledge. Well-documented requirements guide design, enable validation, and support collaboration.

Key Takeaways

•Document to drive design — Each requirement should trace to design elements.
•Use structured formats — Templates ensure completeness and consistency.
•Quantify NFRs — Vague quality requirements aren't actionable.
•Document data explicitly — Entity catalogs become class designs.
•Capture business rules — These drive validation and policy logic.
•Document edge cases — Edge cases reveal design complexity.
•Maintain traceability — Connect requirements to implementation to tests.
•Keep documentation living — Track changes, assumptions, and open questions.
•Adapt depth to context — Interview quick templates vs. full project specs.

Module Complete!

You've now mastered the complete requirement gathering process:

Functional Requirements — What the system must do
Non-Functional Requirements — How well it must perform
Clarifying Questions — Extracting complete information
Documentation — Capturing requirements durably

Module Complete

4 / 4