Project Overview

This is the template for your application’s project document. The project document serves to improve communication between clients and developers.

Text in italics contains guidance that may help you while writing the document. This sentence is an example!

Text in normal font explains recurring solutions in software system design. Some may already fit your needs, but feel free to explore others—they might help you dig deeper into your idea.

As clients, you are invited to modify this document according to the needs of the software system we will build together. We, as developers, will study it carefully.

If this is your first project document, don’t worry. Fill it in as much as you feel comfortable. The purpose of this file is to be written in multiple versions, alternating between clients and developers.

We are available for any question, even “why is the project document in Markdown instead of Word or Google Docs?¹”

Objective

The project aims to build...

Glossary

We must pay close attention to the words we choose in the document to describe our project: if chosen well, they will help us discuss at a higher level throughout the entire development process. If chosen poorly, we will waste time on misunderstandings and fixes. So let’s avoid unnecessary bureaucratic jargon while maintaining the precision of mathematical language.

Business Model

Please briefly inform us here about the business model you have outlined for your software. If it is not ready yet, we can help you find the most suitable solution. Below are examples of the most common models—you can choose one or more, or describe a different one. In any case, we recommend justifying the choice with a couple of paragraphs, e.g.:

Open source: we decided to make this project Free and Open Source Software because...

One-time purchase: we prefer users to buy the product once and for all because...

Freemium: we choose to reach a wider audience so that...

Subscription: ...

Advertising space: ...

In-app purchases: ...

Commissions: ...

Crowdfunding: ...

Partnership: ...

SaaS: ...

Competitor Analysis

A successful project does not necessarily have to be original. If there are competitors, we can learn from their market positioning.

After extensive research into similar solutions, we believe our idea will succeed because...

---

Requirements

Functional Requirements

Core Features

Every time we read a complex feature, our job as developers is to break it down into simpler problems. This section focuses on the most important features of our project.

Additional Features

Scalability is the quality of a product that allows it to be extended after its initial design. If you are aware of directions you would like to take in the future—even after our collaboration—let us know here.

Given the specifications so far, we still need to keep the door open for...

Third-party Service Integrations

Engineering products always integrate with an existing environment. If we choose to use third-party services (free or paid), let’s make it clear here.

Non-Functional Requirements

System Requirements

The environments on which we will distribute our applications (or parts of them): whether it’s a mobile operating system, a set of web browsers, a graphical environment, etc.

The supported device classes and minimum compatibility required are...

Performance

In an online video game, latency is often critical; less so in an email client. We always develop with efficient resource usage in mind, but sometimes increasing performance means reducing result accuracy or increasing scaling costs.

The performance requirements for this software are: ...

Usability

Usability is a well-established discipline: a product is more usable the less cognitive effort is required from its user. Define a target audience and usage scenarios.

Since we are targeting this audience, it is important that...

Security

We follow the principle of Security by design: security is not an add-on. It is equally useful to describe the project’s security methods.

The security requirements for the login phase are:

Two-factor authentication with third-party accounts: since these are the most common personal accounts, we choose to log in via...

Two-factor authentication via email: considering the web server we will set up, we will use it to send confirmation emails...

Two-factor authentication with TOTP: we choose the cheaper Time-based One-Time Password alternative...

Two-factor authentication via SMS: relying on the aforementioned third-party service to send confirmation SMS...

---

Problem Analysis

This is the section that bridges an idea and the beginning of information system design. You are not required to provide a problem analysis as clients. In some cases our development team will have preferences on how to structure it. In others there may already be an existing code base to continue working on.

Use Cases

We invite you to draw use-case diagrams in graphical form, which will provide a detailed overview of the application.

Actors

People or agents who will perform actions. We recommend going beyond the classic user–admin dichotomy. Include yourselves and us developers among the actors. Make wise use of the previously defined glossary: detailing actors well is a very delicate step.

Available Actions

What the actors will be able to do.

Interaction Sequence

Break down the sequence of who-does-what-and-when.

States

Think about states, i.e., situations such as “on/off”, “game in progress/paused/ended”, that are relevant to your application.

Permissions

Permissions are like states associated with actors: if an actor has the right to an action, they can perform it; otherwise they cannot.

User Interfaces

Wireframes

A wireframe is a simple sketch that conceptualises the graphical interface presented to users. Here you are invited to include diagrams of views (what is seen), components (buttons, labels, icons, menus, lists...), transitions (links from view to view), and events (user clicks, timer triggers, etc.). Take a look at https://component.gallery to recognise the most common components and associated terminology. If you need custom components, this is the time to sketch them! For consistency, please save images in the res/ folder and use lowercase filenames without symbols or spaces.

Mockups

A mockup is a high-fidelity model that will be followed closely in the interface implementation. If you provide them, we will take care to respect the graphic style and descriptions reported here.

---

Contract

Development Solution

This section outlines the consulting contract between us developers and you clients, on which an agreement must be reached.

Lifecycle Plan

Here we outline how the project will evolve over time and note the planned versions.

Publication

Here we define the release method of the project, whether on mobile stores, on a physical server, in the cloud, etc.

Expenses

Here we draw up a budget and the expenses related to the project.

User Administration and Post-Launch Support

Here we clarify the user administration dynamics once the project is in production, as well as support and documentation methods (not limited to database administration). Access to the code base must also be agreed upon.

Legal Matters

Copyright: the agreement on the project’s copyright follows...

SLA: a Service Level Agreement with response times on the order of... must be respected

DMCA: in compliance with the Digital Millennium Copyright Act...

EULA: the end-user license agreement will be...

GDPR: to comply with the General Data Protection Regulation...

---

Signed:

Footnotes

1. This footnote explains it: Markdown is a simple markup language for writing documents. It will be useful because we can automatically track the document’s evolution over time. With software like Microsoft Word, developers who are used to plaintext code would be slowed down! ↩