What is a "good" TK on the site?

I can recall surprisingly few materials on the design of sites and programs in Russian written by Russian-speaking authors. This is facilitated by mainly export-oriented development (offshore) and the lack of mass experience in creating information products in our country.
I hope that this article will be useful to those developers and IT-managers who have experienced the problem of creating high-quality documents for the development of the site. Documents that besides spoiled paper would be at least something useful.

Introductory

Why make a technical task (TZ) on the site?
Whatever development technique you use, and no matter how large your site is, you will in any case be confronted with the question: “When will we finish the work, how will we understand that we really finished it?” In software development, and any site a common problem - no one sees the end point. On the one hand, we can say that the final vision of the project should have a project manager. But if the final product matches the manager’s image, but doesn’t match the client’s expectations? And if during the project changes 3 managers?

The consequence of Parkinson's law "ninety-ninety":
The first 90% of the code takes 90% of the development time. The remaining 10% of the code takes the second 90% of the development time.
From the book of A. Cooper " Mental hospital in the hands of patients . "

TK is not just a list of requirements, it is a document. If the contract governs the process of organizational and financial relationships, then the TK regulates the development process and the final result.
In this case, it doesn’t make any difference whether a site is being developed or a small one. The problem of mismatch of expectations may arise regardless of the amount of money spent, only the consequences may be different.
What is this article about.
This article is about what can be useful in the process of writing TK to the site, and what will certainly be desirable to do. But this article is not about how to write project documentation. Ultimately, the main task of the designer is not to write a cool document, but to design a website. A good document is only a reflection of the approach and respect for all participants in the development.
I will add restrictions.
Whenever I talk about writing TK, I mean, of course, a cascade development technique. In the case of other options (for example, extreme programming) other documents are prepared and often on different principles. This is - time.

It is necessary to separate the TK for small and large sites. This is two. Differences between small and large projects are not in the volume of the document at the output, but in the process of their development. If you have only 4 people in the project team, everyone has known each other for a long time, then we can assume the absence of formalism. If several “departments” are engaged in development, and the project team consists of more than 10 employees (ad infinitum), then only a process can manage this horde. The process creates a formalization, and the formalism leaves its mark on the format of the documentation.
')
In fact, the thickness of documents depends on the complexity of the process to a greater extent than on the size of the project.

We will follow the most difficult path.

TK answers questions

TK is initially created for several development participants:

1. Project developers (designers and programmers).
2. Project Manager.
3. Customer.
4. Bureaucrats (they may not participate in the project, but they must also count on them).

Looking back at the listed groups of participants, it can be assumed that the TK should first of all answer their questions. Ideally, all the pre-project documentation in the cascade method is created so as to remove questions in the development process.

So, what questions answers TZ.

For whom the site is created and for what?

The site is created for the customer and for his clients. These are based users of the future project.
The best option would be if in the Terms of Reference you describe all users of the site, both internal and external. This description may include marketing, demographic, social data, goals and objectives of potential users, their requirements for the future site.

How will the tasks of the customer and users be solved?

Actually, if you do not answer this question, then the writing of the TZ can be recognized as paperwork. This is the main and significant question. A separate article may be devoted to it, so we will not dwell on it in detail yet.

How will the project be created?

As I wrote above, the TK (and maybe a separate document) sometimes describes the process of developing a project. This is absolutely necessary if we take into account that a site can be developed according to a different development methodology from the company’s one, which is usually not described in any document. One may torture oneself with dreams about ISO standardization for as long as you want, but what can a meticulous customer show?
According to GOST , a separate section “Stages of system development” is provided. In this section, you can not describe the process in too much detail and install the milestones.

What will be taken at the exit?

TK begins development and puts an end to it.
Ideally, you should go through all the points of the TZ together with the customer, check with the received system and say a week later: “Uh-f. It seems everyone did. ”
“TK is a means of verifying the work performed.” - such a phrase is recorded in the introduction of many of my TK.

What is required for the further launch of the project?

This is a question that the customer should receive in an amicable way. This is a consulting, but in some cases it must be carried out in the design process. It is necessary to plan the number of workplaces, the required software and hardware, etc.

What is the TK

It took me a whole hour to make a decision: to describe the composition of the TOR in the form of a specific clear structure or just to tell about what should be there. Recalling all my TK, I came to the conclusion that the structure of this document changed so often depending on a number of factors, that a clear indication of the structure would resemble poor advice on choosing a suit. Imagine that you are advised to wear something for the evening, without even knowing where you are going.

general information

The first part of the ToR contains an introduction and general information about the document and the project as a whole. Introduction should be written once and for life. As a rule, so many abstract phrases are written there that in each new project it is only necessary to correct a few words.

General information includes:

• Information about the customer and the performer.
  It is necessary to indicate the responsible persons from each side. Specify the documents on the basis of which the development is made. As a rule, such a document is a contract. Status of current document and confidentiality.
• Purpose of the project.
  Specified: what will be used for the resulting product.
• The goals of the creation and the tasks that the resource must solve.
  On the one hand, this is a rather short section, but it ranks first in importance of study. If the goals and objectives are not clearly and immeasurably set, then it can be quite difficult to follow them.
• Description of the project audience.
  Critically important information for developing good and correct sites. It is clear that information about the audience is not only necessary to properly collect, but even more important is to be able to use this information.
  The audience description should contain not only information that marketers love so much (demographics, needs, segmentation, etc.), but also information that is useful for designers and designers: what tasks the user solves, what his goals are in working with the site, what attracts him . Alan Cooper recommends describing the site’s audience not in the form of a faceless mass, but highlighting the characters - describing the collective image of specific people.
• Terms and definitions .
  In a large document, you will be able to use a huge amount of terms and slang expressions that marketing experts or major executives rarely understand. They can read this document, so it’s best to provide a list of definitions for them. I do not amuse myself with the hope that this list has been read at least once in my life, but then I can always refer to it.

The introductory general part of the document contains information on where we started in the design. Of course, in the process of questioning the customer’s specialists, information accumulates an order of magnitude more, but it is not interesting for anyone to read it.
This information is collected in the scope of the project.

Project scope

If you move far away from your home and, turning, to look at it, then from a distance you will not be able to discern the details of the structure. You can count the windows, but you can’t disassemble what material they are, you can admire the architecture (you can not “admire” every house), but you can only guess about the principles of its construction, you will not see the insides of the apartments or the scratched word on the entrance the doors.
The scope of the project is about the same. After reading this chapter, everyone should imagine what will be obtained in the development process, but without going into details at all. You write that the user registration will work on the site, but do not write how exactly it will be arranged, or what fields the user will have to fill out.
The frame level of design in any case passes any project, so it will not be superfluous to write it down. In addition, great chefs from both the developers and the customer do not like to read for a long time, but they love to be aware of everything that is happening. This section should be written including for them.
The project framework is written in the form of scripts for users of the site and describes the overall functionality and interaction with the interface.

Information architecture and interface

The section devoted to information architecture (IA) sites is not standardized by any known standard (the author is not familiar with such yet). But anyone who has developed websites understands that IA is almost the main thing you need to know to develop a website. IA will determine how the site will look and work with users.
To describe the IA you need to describe from top to bottom:

1. Site structure. These are the so-called high-level prototypes.
2. Page templates. Low-level prototypes that describe the site interface itself.
3. Content inventory. Tabular description of the content of each page of the site.

Site structure
The site map is executed graphically in one of the well-known notations: Visio or Garrett . I advise you to draw a site map, because in this case, the resulting structure is the most visible and convenient to use in the future. On the one hand, it may seem that in the form of a list it will be much easier to write a site map, but when you yourself think about the links between different areas of the site, you will, willy-nilly, begin to strike squares on paper.
How to draw the structure of the site using the notations, using Visio, written articles, so we will not dwell on this. The articles are written, however, in English, but you can easily use them.

Do not forget to assign the number of each individual page of the site map. This will be required at the stage of description of the content.

Useful tips when drawing a sitemap:

• Do not feel sorry for the place. Try to position the blocks so that they are separated from each other. This will help map readability.
• Do not shrink. In principle, it is possible to read the text printed in 4 size, but this is already a reason for hatred.
• Align the "squares" of the pages relative to each other, lining up in lines. This will improve the perception of page nesting levels.
• Do not cross the lines. Try to avoid a large number of cross lines. If they intersect, they must “jump over” one above the other. Whoever was engaged in drawing functional schemes at the university, will understand me.
• Sign the card. Sign the card itself, as well as individual blocks. This will allow less confusion in the future.
• Save the file often. Trite, but you just have to remember this. It is not worth remembering once again the relatives of the developers of the Visio program; in fact, they are not to blame for anything.

Sample sitemap.
I usually put the site map in the "Applications" section. As a rule, it is so large that it becomes unreal to place it in the middle of the TK.
Page Templates
At the site map level, each page represents only a “square” for us on a piece of paper. For a designer, coder and programmer, this is not enough to develop a website. We must also know the presence and location of blocks of information and functions on the pages of the site. Therefore, we turn to the site templates. Ideally, each box should be detailed to the layout of each individual page. This is a site prototyping. The use of prototyping depends on the accepted scheme of work in the company-developer, but it is necessary to recognize that it becomes extremely cheap for the customer.
For simplicity, a number of site interface templates are outlined, which are described following the site map.
The template description consists of 3 parts:

1. List of templates. Identifies the main types of pages and describes their use.
2. Typical pattern. The main blocks. Describes the basic blocks of pages in order to reduce the repeatability of information.
3. Description of each template according to the list. Templates are drawn in any graphics package (Adobe Illustrator, Adobe InDesign, MS Visio, etc.), and then supplemented with a brief description.

Disclaimer : site interface templates should not be confused with templates in the software system on which the site will operate. Interface templates describe the number of standard pages, sufficient for site design.

An example of a turn from the TOR with a description of the interface template (airframe).
Content Description
The longest and most tedious part of the work. A description of the content should include a list of all pages of the site with an exact indication of the text placed on each page, pictures, etc. It also indicates which template is used for this page (see above). I recommend using a table for this.
Not always at the time of writing TZ, you can surely know what the content on the site will be: the exact number of information pages, the placement of graphic information, so do not think that this section provides the most accurate description. This is often not the case. But if you describe the required content at this stage, then the project manager based on it will be able to draw up a plan for delivering the content and assess the amount of this information being entered on the site. The client will always have before his eyes a list of what he needs to prepare and edit.
A good description of the content is a pledge of planned work at the stage of launching the site and entering information.

Functional

The description of the site functionality in the technical specification is one of the key sections. This is especially true for sites with a large percentage of software works: e-commerce, online services, etc.
A good example of the description of the functional gives GOST. I recommend keeping the standard when describing the functionality of the programs being developed as part of the site. The following should be described: general system, general functionalities of subsystems and modules, interconnection of subsystems and modules among themselves, and finally, a list of all functions of modules with more or less detailed description of their work. For each module, the objects that are created or used in the work of the program should be listed.
You can also describe the database structure, preliminary work algorithms, but the technical task itself does not require this. According to GOST, such details should be described in further documents: draft and technical projects.
Sometimes when developing large sites, you have to sit for a long time to describe all the functionality of the external and internal parts of the site. Some developers are against such detailing. They believe that the functionality should be described superficially, so that "the client would understand." Complete nonsense! From experience, I can say that there is no unnecessary detail. In case of problems in the project, project managers on both sides become rare primers! They read the TK far and wide trying to prove their case. Therefore, if the functionality in TZ is written in general terms, the client will still force him to do what he needs.

Requirements

A separate section should be devoted to the requirements for the project or the project to the environment. Requirements that can be described in the technical specifications on the site:

• System requirements;
• Staff requirements;
• Reliability requirements;
• Requirements for ergonomics and technical aesthetics;
• Requirements to protect information from unauthorized access;
• Requirements for the safety of information in case of accidents;
• Requirements for types of collateral;
• Software requirements;
• Requirements for information support;
• Hardware requirements;

There may also be a number of specific requirements.
All requirements must be clearly formulated and try not to forget anything from the development aspects of your project.
Of course, in small projects there is no need to prescribe all the above requirements. For example, there is often no staff at all in the website, so such sections are skipped.

Other

In the process of project management, you may notice that there are situations that go beyond the technical task. Perhaps you missed something, or there was an abnormal situation that you previously could not have foreseen. All this will help you to further develop the document, bringing in it new information that will help to use it in communication with the customer and solve problems.

What's next?

TK compiled, signed and entered the work. What's next? Does working with him end at this stage? Not.
The project does not always follow the planned path. We are trying to improve something, change, often changing customer requirements. The terms of reference is a document, not a tablet. With changing requirements for the project should change the technical task. This is usually done by additional documents with a list of changes. Naturally, they are compiled only if it is really necessary, rarely occurs in practice.
You must also be prepared that in the process of in-depth study of the TK, all participants in the development will find errors in the process of working on the project. The number of errors in a large document is directly proportional to its volume and inversely proportional to the time spent writing it. Because time is constantly not enough, we should expect that errors in the TK will occur.

The bottom line.

I wrote this article over a year ago. Quite a lot of time has passed, and during this time I have not written a single large TK. But, after re-reading the information provided, he agreed with everything written here. So good TK on the site should contain:

• General information about the document and its compilers;
• The goals and objectives of the site;
• Description of site users, their goals and objectives;
• Project scope;
• Information architecture (IA) of the site: site map, templates, interface description;
• Description of the site content;
• Description of the site functionality;
• Process Description and Milestones, if required;
• The list of various requirements in the development of the site and verification of the work received.

I hope that the information will be useful to a wide circle of readers.

Useful links:

• GOST 34.602-89.
• Garrett notation .

Yury Shilyaev , website designer, consultant.
Director of the Minsk office of Artics Internet Solutions .

Original: yuri.shilyaev.com/archives/2007/03/21/356/chto-takoe-%c2%abhoroshee%c2%bb-tz-na-sayt.html