When eCommerce website project documentation is prepared correctly, it is possible to anticipate and avoid questions and problems such as these:
- Why do fixed bugs reappear?
- Why was an incomplete version of the product presented to the client?
- Why are there no versions in the documents?
- Why are there differences in the specifications, product and test documentation?
- Where did the new functionality come from?
Let’s paraphrase Murphy’s humorous law a bit and start by saying that if you can be misunderstood, you will be misunderstood. Unfortunately, that happens sometimes. But there is a way out!
In this article, we would like to cover the importance of project documentation, which aims to prevent misunderstandings in the team and when communicating with the customer as much as possible.
The following types of documentation are distinguished:
- User manuals
- Quality control
Types of Documentation Used In eCommerce Projects
Contractual documentation is a written agreement according to which the parties who concluded it have mutual obligations. Contract documentation usually includes:
- Nondisclosure Agreement (NDA)
- Contract (MSA, SLA)
- Project Charter
- Acceptance Protocol
- Project Plan
- Invoice, Purchase Order
Requirements are a set of requests regarding the qualities of the software that are planned to be implemented. The following requirements can be identified
- Functional Requirement Specification
- Software Requirement Specification
- Software Design Specification
- Statement of Work
- User Stories
- Change Requests
- Change Order
Regulatory documentation is a set of standards and instructions that regulate some activity. The following types of such documentation are distinguished:
- Coding standard/Coding convention
- Industry standards
- State legal acts, standards
- Style guides
- Work processes
- Instructions for development tools and collaborative work systems
- “Rules of the Game” (Project Management Plan)
User manuals are materials in written format (or sometimes videos) that will help you understand how to use a service or its administrative panel. There can be, for example:
- User Manual
- Admin Manual
This type includes all the eCommerce documentation developed by the tester to check the quality of the software. Usually, this includes:
- Test Plan
- Test Suite (validation suite)
- Test Scenario
- Test Case
- Test Check List
- Defect Report (priority, severity)
- Test Summary Report
Let’s take a closer look at some of the most important of these documents, their importance, and the rules for creating high-quality, clear, and easy-to-use documents.
The Project Vision document describes in an accessible form the general concept of the project, general requirements, and critical users of the system. It is created at the project initiation stage by the project manager or business analyst, together with the client.
The following questions can be asked of the client to help write a Project Vision:
- What kind of problem are we solving?
- Who else is affected by this issue?
- How will we solve the problem?
- What does the situation look like when the issue no longer exists?
The following table may be helpful:
There is also the so-called Elevator Statement, which can help establish a Vision.
- For <who is the product for?>
- Our product <name the product>
- Is a <product category>
- That provides <main benefit>
- Unlike <our competitor>
- Our Product <statement of differentiation>
The importance of the Project Vision document is that it helps any project participant quickly understand the overall goal, users, and business requirements. This document becomes an essential factor in motivating and inspiring the project team. It emphasises the importance of project tasks, which contribute to team productivity. Its presence helps avoid misunderstanding the purpose of the project from the very start.
What Is a Project Vision, the Qualities of a Good Project Vision Document, Why Is It important?
Project Charter is essentially a body of knowledge about the project with the maximum amount of data. It enables all project participants to be on the same page regarding the scope, terms, budget, and risks. This is its importance. Like a Project Vision, a Project Charter is created at the project initiation stage by the project manager and approved by the client.
The structure of the Project Charter can be summarized as follows:
- The purpose of the project
- Schedule of milestones
- Communications plan and contacts
Google Drive, Notion, and Jira Confluence are tools for writing and storing the Project Charter.
Qualities of a good Project Charter are the following:
- Any team member should have access to this document
- It is necessary to maintain the relevance of the content of the document
- It is necessary to maintain versioning; that is, the entire team must be aware of changes to the document
A well-written Project Charter helps avoid misunderstandings among the parties about the scope, milestones, budget, risks, and communications.
What Is a Project Charter, the Qualities of a Good Project Charter, Why Is It Important?
SRS (Software Requirements Speciﬁcation) is a document that contains system requirements based on which software development is performed. It is created at the project initiation stage by the PM and the team and approved by the client. This document becomes the basis for the evaluation of the project.
Approximate structure for a small SRS document:
1. Purpose of the document
2. Description of functional requirements
- Description in words
- Graphic models
3. Description of non-functional requirements
4. UI description
- Description of fields
- Description of actions
5. Description of interaction with external interfaces
The importance of the SRS document is that with its help, the team and the client can clearly understand what features are planned to be implemented in the project, as well as what non-functional requirements the client has (such as performance, data safety, system safety, etc.). SRS helps avoid misunderstandings with the project scope and when discussing Change requests, which we will talk about later.
SRS Document, Qualities of a Good SRS, Why Is It Important?
A user story is essentially a description of the user’s goal when he/she uses the system. The list of user stories is created by the PM at the project or sprint planning stage.
Usually, each individual user story is written according to the following template:
- As a [user]
- I want to [do something]
- So that [I get the result]
The basic principles for writing user stories are following:
- The requirement must be described in such a way that it is clear to both developers and customers.
- It is worth taking into account a set of criteria by which a separate user story is evaluated known as INVEST (independent, negotiable, valuable, estimable, small, testable). That is, each user story must meet each of the criteria listed.
- User stories must be written in a generally known and approved format
- When writing a user story, a user role is used
It is also worth mentioning the acceptance criteria that accompany each user story. These are the criteria by which it can be said that the user story has been completed.
User stories are extremely important in agile, because they greatly simplify the process of describing product requirements. They are essentially the smallest bricks in the structure of product requirements. With their help, the development team receives clear input data, the creation of which can involve even the client.
What Are User Stories, How to Write Them and What Is INVEST?
A change request is a request to change some functionality of the product previously described in the SRS or add functionality previously out of scope.
Citing one of the Agile manifesto principles: “Responding to change over following a plan”, we must always be ready for change. Another critical issue is that they also need to be managed appropriately.
For example, adding a feature or changing it during the sprint is not practised in a scrum. Changes and evaluations occur when planning the next sprint. If the project is conducted with the help of a waterfall, then change requests are processed and evaluated additionally.
The steps for change management are the following:
- First, it is necessary to analyse the new requirement for the product and determine which functionality will be changed.
- Then it is necessary to determine how much time can be spent on the implementation.
- Next, we proceed to approve the scope and time with the client.
- After approval from the client, we inform the team and start the work
- We verify the change.
- We make appropriate changes to the documentation.
To put it briefly, a change request is a project within a project that can significantly affect the terms, budget, and scope of work.
What Is the Essence and Importance of Change Requests?
A risk is any event that can negatively affect the implementation of the project. Risk management, according to PMBoK, includes the following actions:
- Plan risk management
- Identify risks
- Perform qualitative risk analysis
- Perform quantitative risk analysis
- Plan risk responses
- Monitor and control risks
A risk mitigation plan is drawn up at the project initiation stage. Risks can be identified through a brainstorming process involving developers, PMs, and the client. It is also usually possible to compile a register of standard risks that have accumulated from project to project.
A risk mitigation plan can be a table that should contain the following columns: risk ID, risk description, impact (on scope, budget, deadline), probability (high, medium, low), risk value, and mitigation (the actions which will help to solve the problem).
This document must be constantly updated, noting which risks are still relevant and which are not. A risk mitigation plan is a crucial component of project success because it should not only describe potential risks but also prepare how to deal with them in advance.
The Importance of Drawing Up a Risk Mitigation Plan
- It is better not to use metaphors in eCommerce website project documentation, because, in this case, it can lead to misunderstanding
- Using many fonts at the same time slows down reading. It is better to choose 2 main ones for headings and main text, or limit yourself to one.
- There should be the structure, then the content of the document itself
- It is important to be as precise as possible in wording
- There should not be another unclear word in the description of one term.
5 Primary Recommendations Regarding eCommerce Documentation
In this article, we looked at some types of project documentation that are created for projects in IT and, hopefully, answered the questions that were asked at the beginning of the article.
It helps at all stages of project implementation and in all areas. Without a project vision, we will not understand the client’s business needs; without a project charter – the areas of responsibility of the parties and the main scope, without SRS – for example, functional and non-functional requirements, and so on. In fact, each type of documentation helps to meet the expectations of the interested parties regarding various aspects of its management and to combine the project’s vision of these parties.