Lecture
You can't just go and build a website after a single conversation with the client. First you need to carry out design work. At this stage you gather all the client's ideas, propose solutions, test their viability, and finally record everything in a single document. Moreover, only after the design work can you accurately estimate how much the website will ultimately cost.
To describe requirements for Software, there is the SRS document (IEEE 830) and its variations -- with the inclusion of use cases (that comes from RUP), etc. A technical specification (TS) is essentially a document that describes the requirements for the software.
Before starting work with clients, contractors, or direct reports, it's important to be sure that everyone understood you correctly. When people set vague tasks, don't bother with a brief, and don't want to provide references — they disrupt the process, mislead colleagues, and waste the whole team's precious time.
«The in-house psychic has been fired, so now we'll have to explain things with words»
A task is a goal. It should be described in the logic of an action (draw, analyze, finalize, approve) and carry a sense of completion. The task «publish a post» cannot be considered done if the post has been written but not published.
TR (technical requirements for the website) — this is a list of the functionality and a list of the sections that must be implemented. The client describes how they envision their future website, talks about their wishes, shows examples of resources and «features» they liked, and our manager formulates the TR. Usually this document is a detailed brief drawn up in free form based on the results of an in-person meeting, a phone conversation, or email correspondence. At this stage the complexity of the project is assessed, the price of designing the website is determined, and a contract is signed. In addition, while drafting the technical requirements it becomes clear what will accompany the finished prototype — a specification or a technical specification.
The brief — another important part of setting the task. The brief is context. You can brief someone verbally or in writing, in free form or by filling out a questionnaire. The main thing to remember about a brief — it introduces the contractor to the context. How did we arrive at the idea of creating a social network? Who will the actors be? What will they be able to do? These and many other high-level questions are revealed not in the task, not in the technical specification, but precisely in the brief.
The technical specification - this is what a technical specialist or a product manager writes together with the client when they want to obtain a product. In doing so, they decompose the task, describe the sequence of actions, additional parameters, the involvement of third-party specialists, the API, as well as all the properties and characteristics of the product. A technical specification eliminates guesswork and ambiguity. It must be so detailed, and worded in such terms, that the contractor has no additional questions or need for clarification. Like lawyers with contracts. A technical specification is a document that you pick up, read, and start doing the work.
«Create a social network or an artificial intelligence» — this is a task.
«To create the social network we use the ... framework and the ... programming language. For this we use the ... methodology, ... patterns, we will perform testing with ... . After looking at such a technical specification, a number of questions arise: what happens if there are ... events in the system? Is the ... functionality available to the ... group of users?
A technical specification sheet or simply a specification (spec) - this is what is written for the end users of the system: what's in it and how to use each feature (function). Some software manufacturers (developers) do not create a technical specification, drafting only a spec instead, thereby saving time. A specification is almost the same as a technical specification, but without implementation requirements.
A functional specification (also specs, functional specification document (FSD), functional requirements specification) in systems engineering and software development is a document that defines the functions that a system or component must perform (often part of a requirements specification) (ISO/IEC/IEEE 24765-2010).
The documentation usually describes what the user of the system needs, as well as the requested properties of inputs and outputs (for example, of a software system). A functional specification is a more technical response to the corresponding requirements document, for example the product requirements document «PRD» . In this way, it picks up the results of the requirements analysis stage. In more complex systems, several levels of functional specifications are usually nested within one another, for example at the system level, the module level, and the level of technical details.
How does a technical specification differ from a specification? - A specification is almost the same as a technical specification, but without implementation requirements. Thus, a specification (task document) may contain within it a specification of the object of execution, whereas a specification does not contain tasks.
A specification is what the manufacturer writes, describing the functionality and technical properties of their software product. A technical specification contains requirements, a description of the functionality, the technologies used, timelines for development, testing, deployment, and other sections.
How does a technical specification differ from a brief? A brief is a «fuzzy, more freely composed» technical specification (i.e. one that has no specific information directly concerning the texts, but instead has wishes: regarding the subject, style, structure, emphasis), or it's a kind of «helper» for a client who cannot draw up a technical specification.
Thus, to successfully implement an idea we need:
Remember these simple rules, follow them, and then you'll have far fewer reworks and spontaneous whims from the client!
A technical specification for developers is a kind of recipe for cooking up a successful product. A successful product — one that is easy to maintain, can be developed and changed, doesn't fall apart when the developer changes, and generates profit in any of its forms. Do you want your project to be complete? Great. Write a good recipe for it. The classic ingredients (according to the international standard IEEE-830) are:
The last 2 points are specialized; I advise readers close to development to pay attention to them.
Below I'll go through each of the points in detail. For those who don't want to dig into the details, I'll leave a link to the international standard with a technical specification template: link to document.
This point includes a brief description of the product; it reflects the goal of the project and its distinctive features.
For example: “A dating app in which you can watch short videos in users' profiles and chat”. It also wouldn't hurt to say a couple of words about the product's audience, so the project team can understand its specifics and give you some useful advice. Tell them about its age, character, and geographic location, and any peculiarities that should be reflected in the project.
For example: “These are young people who travel abroad for vacation and are interested in communicating beyond the language barrier, who love taking photos and videos”.
It's worth describing the types of users and their key differences.
For example: “The app should have regular users and moderators, who receive complaints from users about content or profiles. Moderators can view the chat of regular users after a complaint and block a rule-violating account in the service”.
And in conclusion, tell them about the components of your product.
For example: an admin panel used by moderators; a mobile app used by the user to register, add content, take part in chat, etc.
The highest level of skill would be to make a so-called data flow or context diagram, which reflects how users interact with the product, its components, and each other.
A functional map displays the overall concept of the project with the level of detail needed to estimate the scope of work and set priorities. In the traditional format, such a map resembles a site map. But it's most convenient to display it in the form of a mind card (mind map, intellect map). Managers often draw words and the connections between them on a board or a sheet of paper during a meeting — well, that's a mind map. This can be done conveniently in free services (coggle, draw.io, and mindmeister) or simply in Office Word.
It's very important to reflect all the user features in the functional map. As a first approximation, this is simply a set of product functions.
For example: “The app should have registration by email, creation and filling out of profile data, the ability to upload and edit photos and videos, a list of other users' accounts with various types of filters, a text chat, and contacting the support service.
The so-called user flow, or user path, is a sequential list of actions or screens through which a user can move in the process of interacting with the product. Describe how, in your view, the user will interact with the product. This can also be conveniently done with a mind map or simply a list of actions.
For example: “The user opens the app to meet peers. They fill out their profile with data and upload photos and videos. Then the user goes to the feed and filters it by some criteria. As a result, they get a list of relevant profiles, can view them, and message another user in the chat.
The user flow is the general algorithm for working with the product. There are also use cases — this is a detailing of the user flow. In the case of a mobile dating app, you created the user flow across the screens, and then you describe what the user can do on each screen.
For example: on the registration screen the user can:
go to the login screen, register via social networks (Facebook, Twitter), enter an email and password, then repeat it and confirm registration in the email sent to their inbox.
Not only must the product work, but it should also look pleasant. Let's step away from the topic of apps a bit, so as not to make you download them for review. Let's instead look at some nice-looking websites:
We've looked at an example of bad design; now wipe the blood from your eyes and let's move on to discussing the interface. In this part of the technical specification, it's worth attaching references — examples of how you want your product to look. These can be analogues of similar developments or simply examples whose design you liked.
Describe in general terms how you want your product to look, what colors it should have, what elements should be used, what animation you want, etc. If you have a corporate identity or brand book, great, refer to them.
Designers will thank you very much if you specify the interface design style, for example flat design or material design.
The highest level of skill would be to add wireframes — prototypes of the product's interface in the form of approximate schematics.
This section is for specialists. If you're confident in your abilities, then continue reading. The best technical specification also describes the product's architecture, that is, which software components it consists of. In the case of a client-server dating application, the service is broken down into a server part, which stores and processes data and performs some logical operations, and a client part, which displays the data.
The server is decomposed into modules: database, authentication, chat, etc. The client communicates with the server via an API (data transfer interfaces); it's worth specifying its type (REST, WEB, RPC, etc.) and describing the methods, responses, and error handling.
Data is usually stored in a database in the form of special structures, most often tables (for relational databases) and JSON structures (for non-relational ones). Developers will thank you immensely if in the technical specification you specify the database entities (ER models) and describe the stored fields, indicating their data types (string, int, etc.), keys (primary, foreign), whether they are required, and whether they are nullable.
These are general requirements for the product. They can be divided into hardware requirements, security requirements, and performance requirements. In the hardware requirements, you indicate the wishes regarding devices and the operating environment, for example for a dating app this is Android 7.0+ and JDK 8+, iOS 11.0+ and Swift 4.2.
In the security requirements, you can specify that data transmission in the chat must be carried out using SHA-1 encryption and that upon registration the password complexity must be at least 8 bits. In the performance requirements, the connection of components and fault tolerance are discussed; for example, it's worth specifying that the timeout for reading a message in the chat is no more than 1 s and that the app partially stores a cache and can operate offline for a limited time.
There are different types of technical or engineering specifications (specs), and the term is used differently in different technical contexts. They often refer to particular documents and/or specific information within them. The word «specification» is broadly defined as «to state explicitly or in detail» or «to specify».
A requirement specification documents a requirement, or a set of documented requirements, to be satisfied by a given material, design, product, service, etc. This is a common early part of engineering design and product development processes in many fields.
A functional specification is a type of requirement specification, and may show a functional block diagram.
A design or product specification describes the features of the solutions for the requirement specification, referring to either a designed solution or the final produced solution. It is often used to guide fabrication/production. Sometimes the term «specification» is used here in connection with a data sheet (or spec sheet), which can be confusing. A data sheet describes the technical characteristics of an item or product, often published by the manufacturer to help people select or use the products. A data sheet is not a technical specification in the sense of information on how to manufacture.
A specification «in service» or «as maintained» defines the condition of a system or object after many years of operation, including the effects of wear and maintenance (configuration changes).
Specifications are a type of technical standard that may be developed by any type of organization, both in the public and private sectors. Examples of the types of organizations include a corporation, a consortium (a small group of corporations), a trade association (an industry-wide group of corporations), a national government (including its military, regulatory bodies, national laboratories, and institutes), a professional association (society), a specialized standardization organization such as ISO, or common requirements developed without regard to a vendor. One organization usually references (refers to, invokes, cites) the standards of another. Voluntary standards can become mandatory if they are adopted by a government or a business contract.
In radio-electronic engineering, the non-standardized term (professional jargon) datasheet (from English datasheet) is widely used [10].
In different areas of engineering, a specification may contain:
Comments