13 tips for preparing project documents

16 March 2018   |    Nikita Pazin   |   Development of documentation
A person without documents is strictly forbidden to exist
M. A. Bulgakov

We hope that the need for project documentation is already obvious. But often there are many questions related to the volume of these documents and their level of detail, and most importantly, who, at what time, and under what conditions should prepare these documents.

The cost of developing pre-project and project documentation can be a significant 10-20%. In this article, we will look at the main documents and tell you how you can save money while winning the quality of work.

Before starting a new project or restarting an existing one, it is highly desirable to combine the information you have in a single document. This document can be called a "Cover note". It does not have a standard format, because each company has its own volume of information and rules for its distribution (internal documents are confidential and only excerpts can be provided). What information should be included in the accompanying note:

  • Project KPI - if you haven't formulated it before, we recommend that you do it now. If your project has a fixed budget, it is better to specify this information initially. A decent Studio will not adjust the cost of the project to this figure (and why should you cooperate with dishonest ones?), and you can save time on iterations to agree on estimates.
  • Excerpts from your marketing strategy that relate to your project in one way or another.
  • Your opinion about the current project (both strengths and weaknesses) and wishes for the future.
  • Third-party Analytics of your project or business (audits, TNS research, etc.)
  • Requests for the project from your employees or departments - this information will form the basis of the functional requirements for the project.
  • If you already have a resource, it is extremely important to collect feedback from your users (this may be regular partners or customers with whom you have contact). Turning to them for help and advice will not burden them in any way - they will appreciate you much more. If you want to conduct a survey, survey, or research, then it is better to contact companies that specialize in this.

As soon as you will generate a cover memo, you will be able to initiate contact with contractors if you plan to implement the project yourself, then you can skip this point.

Most likely, the contractor will send you a brief to prepare a commercial offer. This is a document containing many different questions. If you have collected information in an analytical note, you will only need to specify its section and copy the information for most items. This is often a formality, but it is necessary due to the fact that the contractor needs to document the first introductory steps for your project.

If the performer offers you an interview, don't refuse it.

Functional requirement

This document is optional, but we recommend that you create the basis for it yourself. This is necessary so that the contractor can develop the technical task taking into account all your needs.

The format of this document is also quite free - just list the functionality, requirements, and restrictions in as much detail as possible. At this stage, it is extremely important to transfer information about the functionality of an existing project to this document, if you need to reproduce it. The performer may simply not know about its existence, and simply not include it in the estimate.

Often some points of your requirements will contradict each other. These contradictions should be discussed with the contractor and the document should be corrected so that it gets rid of such contradictions.

What information should be added to the functional requirements:

  • We recommend that you move your employees 'and clients' project requirements to the functional requirements. At the stage of approving the estimate, you can refuse them, or take them to the next stage of implementation.
  • Technical requirements: download speed, display on specific devices or resolutions, compatibility with a particular software.
  • If you have such a document, you will be able to count on the most accurate estimate (otherwise, the functionality of your project will be counted as standard), and you will be insured against significant adjustments after the development of the technical task or in the process of implementation.
User stories (User story)

You “shook hands” with the contractor and moved on to development. This is the first document that you will be offered to pay for. If the cost fits into your budget, we recommend creating it.

This is a bit like psychotherapy - developing it will help you better understand your clients. If you are planning to implement a SCRUM/Agile project, it will be difficult to do without IT. We do not recommend that you take it on your own if you do not have the appropriate experience.

User story briefly describes:

  • The person using the system.
  • What should be contained in this project.
  • What the user needs it for (goal).
  • Naturally, there will be several such sets, depending on the breadth of the audience and the richness of the project's functionality.
  • User stories help you understand, in particular, whether a user's wish has been fulfilled. You will need this document for further project development and audit.

The second document that you will be asked to pay for. The cost of developing a prototype is already palpable, and you can't refuse it (if the Studio allows you to do this, it should at least alert you).

A prototype of a site or mobile app is an interactive project framework that you can” walk through " by reproducing scenarios of interaction with the interface.

You need to develop a prototype for the following reasons:

  • To get a more accurate view of the project (both in terms of structure and logic) by you and your contractor
  • To identify logical inconsistencies at the initial stage

You need to consider several important features of the prototype:

  • This is not a design, but only a visual list of elements on the page. This is why most elements are black and white.
  • It only works out the front-end functionality, or 1-2 scenarios within the back-end.
  • If the interface of the project's administrative or service panel is important to you, we recommend that you also reproduce this functionality in the pototype.

Should I work on usability at the prototype stage? In this case, there is no universal answer. The General advice is: if it is possible to do this within the framework of the prototype, then do it, but first agree on the presence of elements and General navigation logic. In this case, the ui / ux specialist will not be customized, and you can start the next work.

Sometimes it is much more effective to prepare a prototype for even a small functional upgrade than to do and then edit "live".

Can I develop a prototype myself to save money? Yes, if you have the time and experience. However, in this case, we recommend that you specify the format in which the prototype will be needed by the performer (they will need to make a number of changes to it to ensure its consistency with the technical task).

Technical specification

After the prototype is developed and approved, you can start writing the technical task. These works must be entrusted to the contractor or a third-party professional ( having previously agreed on the format and requirements for the TOR on the part of the contractor).

We recommend that the TOR be issued as an Appendix to the project development agreement.

Sections of the terms of reference should be strictly structured, and described as a General introductory and specific local task that the developer or their team needs to implement.

What should the TK contain?:

  • Business processes implemented in the project
  • Algorithms, in the form of flowcharts and descriptions
  • Description of the front-end and back-end logic
  • Lists of fields and their data types that are interacted with for correct database design
  • Technical requirements for hardware or software
  • Integration procedure, format, and Protocol for data exchange
  • Technological and functional limitations
  • Testing conditions for successful completion of the project
  • Conditions for transferring data from a pre-existing project
  • Description of the project launch (implementation) process.

If the project is implemented using SCRUM, the TOR can be developed separately for each sprint. It will be updated with each sprint. However, in this case, you need a roadmap for further development of the project, so that the performer understands what he needs to take into account when designing the project architecture.

This also explains the answer to the question “what to do with your TK?” . In the process of implementing the project, you have to deviate from the TOR for various reasons, and so that by the time of delivery or if necessary, read the documentation for the project, you do not have to give up in confusion, we recommend updating this document at least weekly. The Customer is primarily interested in this, but it is not uncommon for this work to be taken over by a Manager on the performer's side.

Please note that, as a rule, integration is described in the TOR only from the project side. If another service does not have regular integration or it is not suitable for your tasks (for example, 1C enterprise), then all questions will remain on your side, because the performer will confirm the working integration by simply “running” the reference file. If you need to conduct development in parallel, do not delay it.

Road map (roadmap) project

A small document that is often attached to the TOR. It describes the further development of the project (sometimes several scenarios) and the stages of their implementation. The document is " live” and requires updating after each stage of development.

This concludes our review. We wish you clear documents and successful projects.

Another articles