Starting a software development project without proper documentation is one of the easiest ways to create confusion, delays, unexpected costs and disagreements later.

A software project does not become clear simply because everyone has discussed the idea on calls or exchanged messages. Before development starts, the business objective, product requirements, scope, technical expectations, responsibilities, acceptance criteria and delivery process should be documented.

The exact documents required depend on the size and complexity of the project, but most professional software projects should establish five major areas before development begins:

1. Business requirements
2. Product and functional requirements
3. Technical requirements
4. Project delivery and commercial requirements
5. Security, testing and handover requirements

The purpose of documentation is not to create paperwork for its own sake. Good documentation gives the client, product team, designers, developers, testers and project managers the same understanding of what is being built, why it is being built and what successful delivery means.

This guide explains the documents that should be prepared before starting a software development project, what each document should contain, why it matters and what can go wrong when it is missing.

---

Quick Answer: What Documents Are Needed Before Software Development Starts?

A software development project should generally have the following documentation before development begins:

Document	Primary Purpose
Project Brief	Defines the business problem, objective and expected outcome
Business Requirements Document	Explains what the business needs
Product Requirements Document	Defines product functionality and user requirements
Scope Document	Defines what is included and excluded
Functional Specification	Describes how features should behave
Technical Specification	Defines technical expectations and constraints
Software Architecture Document	Explains how the system will be structured
UI/UX Requirements	Defines user interface and user experience expectations
API / Integration Requirements	Defines communication with external and internal systems
Database Requirements	Defines important data structures and relationships
Security Requirements	Defines security and access expectations
Testing and QA Requirements	Defines how functionality will be validated
Acceptance Criteria	Defines when a feature or project is considered complete
Project Plan	Defines milestones, dependencies and delivery stages
Statement of Work	Defines commercial and contractual responsibilities
Change Request Process	Defines how changes to scope will be handled
Deployment Plan	Defines how the application will move into production
Handover Requirements	Defines what must be transferred to the client at delivery

Not every project needs a separate document for every item above. For a small project, several areas may be combined into one specification. For a large application, SaaS platform, enterprise system or AI product, each area may require its own documentation.

The important thing is not the number of files.

The important thing is that the required decisions have been documented clearly.

---

Why Documentation Matters Before Development Begins

One of the biggest mistakes in software development is treating documentation as something that can be completed after coding starts.

Documentation should support development, not describe decisions that were never properly made.

When requirements are unclear, developers have to make assumptions.

For example, a requirement might say:

Users should be able to log in.

That sounds clear until the team starts asking questions.

Does login use email and password?

Can users log in with Google?

Is mobile number login supported?

What happens when the password is forgotten?

How many failed attempts are allowed?

Should two-factor authentication be enabled?

Can administrators force a password reset?

What happens when an account is inactive?

Should users remain logged in after closing the browser?

A simple sentence can therefore represent dozens of product and technical decisions.

Documentation brings those decisions into the open before they become expensive development changes.

Good documentation helps answer five fundamental questions:

What are we building?

Why are we building it?

How should it work?

What is not included?

How will we know that it is finished?

When those questions are unanswered, development becomes interpretation rather than execution.

---

1. Project Brief

The project brief is the starting point.

It explains the project at a high level and creates a common understanding between everyone involved.

A project brief should not attempt to describe every technical detail. Its purpose is to establish the reason the project exists and the outcome it is expected to achieve.

What should a project brief contain?

A useful project brief should normally include:

• Project name
• Business objective
• Problem being solved
• Target users
• Expected business outcome
• High-level product description
• Primary features
• Business constraints
• Important deadlines
• Budget expectations, when applicable
• Key stakeholders
• Success criteria

For example, saying:

Build an e-commerce application

is not enough.

A stronger project brief would define:

• Who the customers are
• What they need to purchase
• How products will be managed
• How orders will be processed
• Which payment methods are required
• What business problem the platform solves
• What the first release must accomplish

The project brief establishes the context for everything that follows.

---

2. Business Requirements Document

The business requirements document explains what the business needs from the project.

This document should focus on business outcomes rather than implementation details.

For example:

The business needs an online platform that allows customers to create accounts, browse products, purchase products, track orders and receive order notifications.

This describes the business requirement.

It does not yet dictate exactly how developers must implement it.

What should a business requirements document contain?

A business requirements document may include:

Business problem

What problem exists today?

Business objective

What should the software accomplish?

Business goals

What measurable outcomes are expected?

Stakeholders

Who owns, manages, uses or depends on the system?

Target users

Who will actually use the product?

Business processes

How is the relevant business activity performed today?

Current problems

What are the weaknesses in the existing process?

Desired future state

What should change after the software is implemented?

Constraints

Are there regulatory, financial, operational or organizational limitations?

This document is particularly important for projects where the development team is working with a non-technical business owner.

---

3. Product Requirements Document

The Product Requirements Document, commonly called a PRD, is one of the most important documents in a software project.

It translates business objectives into product requirements.

The PRD answers:

What should the product do?

It should describe the features, user journeys, behaviours and expected outcomes of the product.

What should a PRD contain?

A detailed PRD may contain:

• Product overview
• Target users
• User personas
• User journeys
• Feature list
• Functional requirements
• User stories
• Business rules
• User roles
• Permissions
• Edge cases
• Error scenarios
• Notifications
• Search requirements
• Reporting requirements
• Administrative functionality
• Acceptance criteria
• MVP priorities
• Future features

For example, instead of writing:

Users can upload documents.

The PRD should explain:

• What file types are supported?
• What is the maximum file size?
• Where are files stored?
• Can users upload multiple files?
• Can files be deleted?
• Who can access them?
• Are uploaded files scanned?
• What happens when an upload fails?
• Can administrators access the files?
• Does the user receive a notification after upload?

That level of detail prevents developers from having to invent product behaviour.

For a full breakdown of what separates a usable requirement from a vague one — functional vs non-functional requirements, business rules, acceptance criteria, and the rest — see our guide to what should be included in a software requirement document.

---

4. Scope Document

The scope document defines the boundaries of the project.

This may be one of the most commercially important documents in software development.

A project can fail even when the software itself works perfectly if nobody agrees on what was actually included.

A strong scope document should clearly define:

Included functionality

What will be built?

Excluded functionality

What will not be built?

Platforms

Is the product being developed for:

• Web
• iOS
• Android
• Desktop
• APIs
• Internal systems
• Multiple platforms

Integrations

Which external systems are included?

User roles

Which roles are supported?

Deliverables

What exactly will be delivered?

Milestones

What are the major delivery stages?

Assumptions

What assumptions were made when estimating the project?

Dependencies

What does the project depend on?

This distinction is critical.

A feature being related to the product does not automatically mean it is part of the project scope.

For the full breakdown of in-scope vs out-of-scope functionality, responsibilities, dependencies, and how to handle change requests without letting scope creep in unnoticed, see our guide to what should be included in a software project scope document.

---

5. Functional Specification

Functional documentation explains how individual functions should work.

The PRD may say:

Customers can place an order.

The functional specification should explain the actual behaviour.

For example:

1. Customer adds a product to the cart.
2. Customer selects quantity.
3. System validates stock availability.
4. Customer enters shipping information.
5. System calculates applicable charges.
6. Customer selects a payment method.
7. Payment is processed.
8. Order is created.
9. Inventory is updated.
10. Confirmation is generated.
11. Customer receives confirmation.

This level of detail is important because different people can interpret the same feature differently.

A functional specification converts the requirement into expected system behaviour.

---

6. Technical Specification

The technical specification defines important technical expectations before development starts.

It should not necessarily prescribe every line of implementation, but it should establish the major technical boundaries.

Depending on the project, it may include:

• Application type
• Supported platforms
• Preferred technology stack
• Backend requirements
• Frontend requirements
• Database requirements
• API requirements
• Third-party services
• Hosting requirements
• Infrastructure expectations
• Authentication approach
• Authorization model
• Performance expectations
• Scalability requirements
• Availability requirements
• Logging requirements
• Monitoring requirements
• Backup requirements
• Development environments
• Production environment
• Deployment requirements

For example, if the software must integrate with an existing enterprise system, that dependency should be identified before development begins.

Otherwise, the team might design an architecture around assumptions that later prove incorrect.

---

7. Software Architecture Document

The architecture document explains how the major parts of the system fit together.

It provides the structural view of the product.

A software architecture document may define:

• System components
• Frontend architecture
• Backend architecture
• Database architecture
• API architecture
• Authentication architecture
• Integration architecture
• Infrastructure
• Hosting
• Data flow
• Communication between services
• Third-party dependencies
• Scalability strategy
• Reliability considerations

For larger applications, the architecture document should also identify boundaries between major services or components.

For example:

User Interface → API Layer → Business Logic → Database

may be appropriate for one product.

Another product might require:

Web Application → API Gateway → Multiple Services → Queue → Databases → External Systems

The architecture should match the actual needs of the project.

There is no value in making a simple application unnecessarily complicated.

---

8. UI/UX Requirements

Software functionality and user experience should not be treated as completely separate.

The project documentation should establish what the user experience is expected to accomplish.

UI/UX documentation can include:

• Page or screen list
• User flows
• Wireframes
• Design requirements
• Navigation structure
• Responsive requirements
• Accessibility requirements
• Design system
• Interaction behaviour
• Form behaviour
• Error states
• Empty states
• Loading states
• Mobile behaviour
• Desktop behaviour

A common mistake is documenting only the ideal or successful user journey.

A mature specification also documents what happens when something goes wrong.

For example:

What happens if payment fails?

What happens if the API is unavailable?

What happens if a user enters invalid information?

What happens if no search results are returned?

Those states are part of the actual product experience.

---

9. API and Integration Documentation

If the system communicates with other applications, API and integration requirements should be documented before implementation.

This is especially important for:

• Payment systems
• CRM systems
• ERP systems
• Authentication providers
• Email platforms
• Messaging systems
• Shipping services
• Analytics platforms
• AI services
• Internal enterprise systems

Integration documentation should define:

• System being integrated
• Purpose of integration
• Authentication method
• API endpoints
• Request structure
• Response structure
• Required fields
• Optional fields
• Error handling
• Retry behaviour
• Rate limits
• Webhooks
• Data mapping
• Failure scenarios

A project can appear simple until an external integration is introduced.

That is why integrations should be identified and documented early.

---

10. Database and Data Requirements

If the software stores important information, data requirements should be documented.

Depending on the project, this may include:

• Data entities
• Important fields
• Relationships
• Data ownership
• Data validation rules
• Data retention
• Data deletion
• Data migration
• Data access
• Data backups
• Reporting requirements

The documentation does not always need to contain the final production database schema before development starts.

However, the important data structures and relationships should be understood early enough to prevent major architectural changes later.

---

11. Security Requirements

Security should not be added at the end of development.

The project should establish security expectations before implementation.

Depending on the product, security documentation may address:

• Authentication
• Authorization
• User roles
• Password policies
• Multi-factor authentication
• Session management
• Encryption
• Secrets management
• Data protection
• Access logging
• Audit logging
• Backup security
• Administrative access
• API security
• File upload security
• Incident handling
• Data retention

The requirements should reflect the nature of the application.

A public marketing website does not have the same security requirements as a financial platform or enterprise application containing sensitive business information.

---

12. Testing and QA Requirements

Testing should also be defined before development is finished.

The project documentation should explain how quality will be evaluated.

This may include:

• Functional testing
• Integration testing
• API testing
• Regression testing
• Performance testing
• Security testing
• Compatibility testing
• Mobile testing
• User acceptance testing

The team should also define:

Who tests?

What is tested?

When is it tested?

What happens when a defect is found?

What severity levels are used?

What must be fixed before release?

This prevents the phrase:

It works on my machine.

from becoming the project acceptance standard.

---

13. Acceptance Criteria

Acceptance criteria define when something is actually complete.

This is one of the most overlooked parts of software documentation.

For example, instead of:

Build a login feature.

Acceptance criteria might specify:

• User can log in using registered credentials.
• Invalid credentials produce an appropriate error.
• Passwords are not exposed in responses.
• Locked accounts cannot authenticate.
• Password reset functionality works.
• Session behaviour follows the defined requirements.
• The feature works on supported devices.
• Required test cases pass.

Acceptance criteria should be measurable enough that two reasonable people can independently determine whether the requirement has been met.

That is the standard to aim for.

For the full breakdown of what belongs in an acceptance criterion — preconditions, failure behaviour, edge cases, and how to prove it was met — see our guide to what should be included in software project acceptance criteria.

---

14. Project Plan and Milestones

The project plan explains how the work will be delivered.

It should normally identify:

• Project phases
• Major milestones
• Dependencies
• Review points
• Deliverables
• Testing period
• Client approval points
• Deployment stage
• Final handover

For larger projects, milestones should correspond to meaningful outcomes rather than arbitrary dates.

For example:

Milestone 1: Discovery completed

Milestone 2: Architecture approved

Milestone 3: Core product functionality completed

Milestone 4: Integration completed

Milestone 5: QA completed

Milestone 6: User acceptance completed

Milestone 7: Production deployment

This gives everyone a clear view of progress.

---

15. Statement of Work

The Statement of Work, or SOW, defines the commercial and delivery agreement between the client and development team.

A professional SOW should typically establish:

• Project scope
• Deliverables
• Responsibilities
• Milestones
• Timeline
• Commercial terms
• Payment structure
• Client dependencies
• Change management
• Acceptance process
• Ownership
• Intellectual property
• Support expectations
• Warranty or post-launch terms

The SOW should complement technical documentation.

It should not be the only document describing the project.

---

16. Change Request Process

No software project stays completely unchanged.

New ideas appear.

Business priorities change.

A technical constraint is discovered.

A stakeholder requests additional functionality.

The problem is not change.

The problem is undocumented change.

Before development begins, the project should establish how changes will be evaluated.

A basic change request process can define:

1. Change request submitted
2. Request reviewed
3. Technical impact assessed
4. Schedule impact assessed
5. Cost impact assessed
6. Client approves or rejects change
7. Documentation updated
8. Development proceeds

This prevents informal requests from silently expanding the scope.

---

17. Deployment Plan

The project should establish how the application will reach production.

Deployment documentation may define:

• Hosting environment
• Infrastructure
• Production environment
• Domain configuration
• Environment variables
• Secrets
• Build process
• Deployment procedure
• Database migration
• Rollback procedure
• Monitoring
• Logging
• Backup
• Post-deployment checks

The deployment process should not be invented on the day the product is supposed to launch.

---

18. Handover Documentation

The project is not necessarily finished when the software goes live.

The client should know how to operate, maintain and control the system.

Handover documentation may include:

• Source code access
• Repository access
• Hosting access
• Domain access
• Database access
• Cloud infrastructure access
• Third-party account access
• Deployment instructions
• Environment documentation
• API documentation
• Architecture documentation
• Backup procedures
• Monitoring information
• Administrative credentials
• Support instructions

The exact handover requirements depend on the project, but ownership should never be ambiguous.

For the full breakdown of what a proper handover covers — including a downloadable checklist — see our guide to what should be included in a software development handover document.

---

What Documents Are Essential for an MVP?

An MVP does not require the same documentation depth as a large enterprise platform.

However, "MVP" does not mean "skip documentation."

A practical MVP documentation set can include:

1. Project Brief
2. Product Requirements
3. Scope
4. Functional Requirements
5. Technical Specification
6. Basic Architecture
7. Acceptance Criteria
8. Project Milestones
9. Testing Requirements
10. Deployment and Handover Requirements

The documentation can be concise.

What matters is that important decisions are explicit.

---

What Documents Are Needed for an Enterprise Software Project?

Enterprise projects generally require deeper documentation because there are more stakeholders, systems, dependencies, compliance requirements and operational risks.

An enterprise project may require:

• Business Requirements
• Product Requirements
• Detailed Functional Specification
• Technical Specification
• Architecture Documentation
• Integration Documentation
• API Documentation
• Data Model Documentation
• Security Requirements
• Infrastructure Architecture
• Identity and Access Requirements
• Testing Strategy
• Performance Requirements
• Disaster Recovery Requirements
• Deployment Documentation
• Operational Runbooks
• Monitoring Requirements
• Data Migration Plan
• Change Management Process
• Acceptance Criteria
• Handover Documentation

The larger the project, the more expensive undocumented assumptions become.

---

What Documents Are Needed for an AI Development Project?

AI projects introduce additional requirements because the behaviour of an AI system may depend on models, data, prompts, retrieval systems, evaluation methods and external services.

An AI project may need documentation covering:

• Business objective
• AI use case
• User workflows
• Input data
• Output expectations
• Model requirements
• Model selection criteria
• Prompt requirements
• Retrieval requirements
• Knowledge sources
• Vector database requirements
• Tool and API access
• Agent behaviour
• Guardrails
• Evaluation criteria
• Hallucination handling
• Security
• Privacy
• Logging
• Cost controls
• Monitoring
• Human review requirements

For an AI application, simply writing "integrate AI" is not a useful technical requirement.

The project needs to define what the AI is expected to do, what information it can access, what it cannot do, how its output will be evaluated and what happens when the system produces an incorrect or uncertain result.

---

Common Documentation Mistakes

1. Starting development from conversations alone

Calls and messages are useful.

They are not a substitute for structured project requirements.

Important decisions should be recorded.

---

2. Describing features without defining behaviour

Saying "the application should support payments" does not define how payments work.

The workflow, failure conditions, supported methods and expected outcomes should be documented.

---

3. Focusing only on the happy path

Real systems encounter failures.

Documentation should account for:

• Invalid input
• Missing data
• API failures
• Payment failures
• Authentication failures
• Network problems
• Duplicate requests
• Timeouts
• Permission problems

---

4. Not defining what is excluded

An incomplete scope document creates expectations that grow throughout the project.

What is excluded should be written clearly.

---

5. Treating acceptance as subjective

"Looks good" is not a useful acceptance criterion.

The project should establish measurable conditions for completion.

---

6. Ignoring client responsibilities

Software teams frequently depend on the client for:

• Content
• Credentials
• API access
• Business decisions
• Approvals
• Design assets
• Data
• Third-party accounts

Those dependencies should be documented.

---

7. Leaving ownership and handover until the end

Ownership should be understood before development begins.

The project should establish who owns the code, infrastructure, accounts, data and documentation.

---

A Practical Pre-Development Documentation Checklist

Before development starts, ask these questions:

Business

• Is the business problem clearly defined?
• Is the project objective documented?
• Are the target users identified?
• Are success criteria defined?

Product

• Are the core features documented?
• Are user journeys defined?
• Are user roles and permissions documented?
• Are important edge cases identified?

Scope

• Is everything included clearly listed?
• Is everything excluded clearly listed?
• Are assumptions documented?
• Are dependencies identified?

Technical

• Is the expected architecture understood?
• Are integrations identified?
• Are platform requirements defined?
• Are infrastructure requirements known?
• Are database requirements understood?

Security

• Are authentication requirements defined?
• Are access permissions documented?
• Are sensitive data requirements understood?
• Are security responsibilities assigned?

Testing

• Are acceptance criteria defined?
• Is the testing approach documented?
• Are supported platforms known?
• Are release conditions defined?

Delivery

• Are milestones defined?
• Are client responsibilities defined?
• Is the change request process established?
• Is deployment understood?
• Is handover defined?

If several of these questions cannot be answered, the project may not be ready for development.

---

The Ortem Pre-Development Readiness Test

At Ortem Technologies, a useful way to think about project readiness is to divide it into five questions:

1. Business Readiness

Do we understand why the software is being built?

2. Product Readiness

Do we understand what needs to be built?

3. Technical Readiness

Do we understand how the system needs to operate and what technical constraints exist?

4. Delivery Readiness

Do we know how the project will be executed, reviewed and accepted?

5. Ownership Readiness

Do we know what happens after delivery and who owns the software, infrastructure, data and documentation?

A project is significantly easier to execute when all five areas have been addressed.

---

Do You Need Every Document as a Separate File?

No.

This is an important distinction.

Documentation quality does not depend on the number of documents.

A small application may combine several areas into one project specification.

A larger project may require dozens of separate documents.

For example:

Small project

One comprehensive project specification may contain:

• Business requirements
• Product requirements
• Scope
• Functional requirements
• Technical requirements
• Acceptance criteria

Medium project

Separate documents may be created for:

• Product requirements
• Technical specification
• Architecture
• API
• Testing
• Deployment

Enterprise project

Each major area may have its own controlled documentation and review process.

The objective is clarity, not paperwork.

---

What Happens When Documentation Is Missing?

Poor documentation usually creates one or more of these problems:

Different interpretations

The client imagines one product while developers build another.

Scope expansion

Additional expectations appear during implementation.

Repeated discussions

The team keeps revisiting decisions that should already have been finalized.

Development delays

Developers cannot proceed without clarification.

Unexpected costs

Changes discovered late can require redesign or redevelopment.

Testing disputes

The client and development team disagree about what constitutes completion.

Handover problems

Important access, infrastructure information or documentation is missing at the end.

Good documentation does not eliminate every project problem.

It significantly reduces avoidable ambiguity.

---

Final Takeaway

Before starting a software development project, do not ask only:

"Do we have the designs?"

Ask a much broader question:

"Do we have enough documented information for the development team to build the right product without guessing?"

A professional software project should establish the business objective, product requirements, scope, functional behaviour, technical expectations, architecture, integrations, security requirements, testing approach, acceptance criteria, delivery milestones and handover requirements before development is fully underway.

The exact documentation will depend on the type of software, project size and business requirements.

The principle remains the same:

Document the important decisions before those decisions become expensive to change.

At Ortem Technologies, we believe good software development starts before the first line of code is written.

It starts with clarity.

If the words "requirements," "scope," "specification" and "Statement of Work" are already blurring together for you, that confusion is worth resolving directly — see the difference between requirements, scope, specifications and a Statement of Work.

Need a second opinion on whether your requirements are development-ready before you brief a team? That is the first thing we check in a custom software development engagement.

Talk to us about your project →