Organization of functional requirements for a large project

    This article is about how to organize requirements on a large project with a bunch of subprojects that are constantly changing; organize the requirements so that readers are happy and comfortable reading them (as much as possible for technical documentation), and writers write.

    We are talking about the organization of ready-made requirements (requirements have already been received and formulated, and now work is being done with them). And in this context, a requirement is a description of a certain functionality (in my case, to a site), in a language that is understandable to the developer, customer, mere mortal, giving an idea of ​​how it should work.

    What is written below is not the ultimate truth, it is only a description of the problems that the development team faces in working with requirements on a daily basis, and tools with which to solve them.

    Where did the need for all this come from? Why is this all?

    The idea of ​​creating a requirements organization system appeared in the work on the projects of one of the Russian Internet retailers. In addition to the retail website of the online store (where I’m selling, I’m not afraid of the word everything - diapers, buckwheat, clothes, tickets), it is also a platform for working with corporate clients, all kinds of services, brand zone). All of this has its own requirements (most have their own business customer), which must be described and stored and processed somewhere, and also solve problems. Key (of course, there are more of them, but the list below is the most relevant) that I have identified for myself:

    1. Tasks (analytics, development, testing) are carried out by different people, and therefore it is necessary that any non-participant can at any time be oriented in the requirements and understand what's what.

    2. Requirements are constantly updated, → we need a mechanism to quickly and clearly make changes to existing requirements.

    3. The requirements of the subprojects refer to the requirements for the retail site → a simple and clear organization of documentation is required and always working links.

    I think the first point does not need to be detailed - everything is already clear.

    Requirements are constantly updated

    The obvious thing, it would seem: any change on the site, in addition to the block to which the change relates, can affect other functionality. It is very important not to lose sight of this. Accordingly, it is necessary to organize the documentation in such a way that the list of functionalities related to the modifiable functionality is before your eyes.

    And one more thing: it often happens that, for example, nothing has changed in the user script, only the data exchange script has changed (the site user will not even feel anything). But if we have everything in one requirement (the requirements for the user script, the data exchange script, and the requirements for the user interface), most likely this is all interconnected. As a result, making changes only to the system scenario, we affect everything, the change is applied to one big demand - it is inconvenient. Therefore, I am for crushing all the requirements. How - I will tell below.

    The requirements of subprojects refer to the requirements for a retail site

    . What’s the point. I’ll try to explain with a simple example from life.
    It is clear that, regardless of the size and capabilities provided by the online store, there is some basic functionality without which the online store is no longer an online store. For example, checkout functionality. (Without the ability to place an order, this will not be an online store, but a catalog.) And this functionality runs through the entire site. So we screwed on the site the ability to purchase goods directly from third-party suppliers - a separate subproject, individual requirements. But here there is the process of placing an order, which, in general, is the same as for ordinary goods. And what are we doing? Just write: “see requirements for the retail site "- link. No need to write a new requirement - to waste time, place in the document. Profit

    But in fact, this method is full of dangers. As I wrote above, the requirements are constantly changing: some functionality is being updated, they are abandoning something, often the requirements immediately go to the site, bypassing the analytics with its documentation. As a result, the developer develops one thing, the documentation says the other, on the site - the third.
    And what happens?
    The developer did "similar to a retail site." It's time for business testing. What does the customer see? On the main site because , in his project - different . And after all, everyone understands that this should be like on the main site. But how to explain that at the time of development on the main site it was just like that ? And so the assessment was given for suchimplementation (there was no other at that time)? As a result, we have to redo, and this is a new cost, not to mention the discontent of all participants.

    Of course, in the framework of the project with suppliers, instead of a link, one could simply describe the current functionality on a retail site. But this:
    1) duplication (which means if it is necessary to update the requirements for functionality, then this is plus one more point in another document that you must remember to touch upon the update),
    2) even more text in the document (and you won’t name the documentation anyway) very much entertaining literature - and if it is very large, then unconsciously begin to feel uncomfortable),
    3) and therefore need more from b about ng bigger amount of text to extract information.

    You can simply say: “look how it's done on the site - here too.” But if at the moment between when the evaluation of the implementation was given and when the implementation began, something changes on the site, then the evaluation will no longer correspond to reality.

    And what to do then?

    I highlighted several tools that help solve the problems listed above. Below is a list of them with comments and pictures.

    Firstly, all requirements should be divided according to their purpose .

    1. User scenarios: how the work with the site looks for the site user.
    2. System scenarios: what happens inside the site when a user works with the site - data exchange scenarios, calculations, internal algorithms.
    3. Requirements for the user interface: what object of the user interface of the site behaves like, what is its source, restrictions - depending on what element we are talking about (text field, pop-up, drop-down list, frame, etc.) .

    Firstly, it’s convenient: for a tester to write test scripts, only user scripts need to be read. The business customer agrees with them and the requirements for the user interface (it is important that this works and looks on the site in accordance with the idea of ​​how it is done inside - it is up to the technical experts to decide). Similar to the designer. But the analyst, in order to understand how feasible this is, also needs system scenarios. According to them, the site developer will coordinate the interfaces with a representative of a third-party system. Etc.

    Secondly, when the situation arises that only the internal system scenario changes (what I wrote above), it will change: it will not be necessary to get into a big requirement, where everything is crammed, and rewrite it.

    I used to think it was cool to keep three types of requirements in three relevant documents (User Scripts, System Scenarios, User Interface Requirements documents), or at least in different sections of one document. And so it seems to be right. Combining requirements with this method is done at the expense of requirement codes (I will tell you about requirement codes below). But in conditions of limited time, it’s easier for me to have all three types of requirements in one place - so that it is at hand.
    So I am for flexibility, and not for blindly following the rules - you need to choose the option that is convenient (while forgetting that the requirements are read by developers, testers, and people without an appropriate technical background). Considering the possible consequences (maybe now it’s better to put a little more effort, but then they will need less?).

    Secondly, each requirement must have its own individual code .

    Well, this is understandable and logical, as everyone does. I went a little further in this matter - in the request code I try to reflect: connections, versions, some additional data:

    It is more correct to use " SUC " instead of " TECH " - system use case, but the customer may perceive it incorrectly (somehow we were already asked to rename the request code, because the abbreviation turned out to be BR ED).

    The fourth column - CR - this is exactly the same "some kind of additional data." In this case, the data needed by the manager to understand whether a change was made to the requirements within the framework of the main scope or for some money.
    And the version is just what will allow us to beautifully get out of the situation when it was done “similarly to the main site”, and the main site has changed by the time of testing. Next, I’ll tell you how, in my opinion, it’s cool to draw up requirements, and about versions there.

    Otherwise, in the picture, it seems to me, everything is quite clearly reflected.

    Third: registration of requirements .

    I do it like this:

    ProI already wrote the requirement code a little higher.
    In related requirements placed requirements of codes that describe the same functionality, but in terms of, for example, the exchange of data (ie, what I'm told, when called upon to separate requirements for three types) - respectively code requirements from related requirements should be the same, excluding the type part. Names may also be different.
    Child requirements are extensions to existing requirements (in the example, this is an iFrame requirement that becomes available as part of the described requirement). You can add the “Parent requirement” field, where, accordingly, the requirement code will be displayed, the extension of which is the described requirement (fuh!). ERP
    Fieldsand Payment system - optional, needed only if ERP and Payment system are mentioned in the described requirement (and if not, then the fields are not needed at all - why produce extra information?). This is very convenient, by the way, at the stage of coordination: when representatives of various systems must agree on a document, they do not have to read the entire document at all, it is enough to limit themselves to the requirements where their work is affected.
    You can add the “Layouts” field here, if such exist, and display a link to them there (the developer will be grateful). You can add a link to a task in Jira (Redmine, etc.) - in general, anything you want.
    Next is the Versions section - in my opinion, one of the key blocks.
    How to work with him and what is its essence?

    When a change in requirement comes, then:
    1) The requirement is changed by the writer (logically),
    2) A new line is created in the "Versions" section, where:
    • Version code - the code of the modified requirement plus the date the version was created;
    • The source - where did we get this change from (from a letter, in correspondence, task, etc.) - is useful when you need to figure out why what has changed and who and at what moment became the initiator;
    • The new meaning is what has changed in demand.

    When we refer to a requirement from another document (subproject), we already indicate the version of the requirement to which we refer. Feel it? Feel it?

    1. The developer in the requirements of the subproject read: “see version of the retail site requirement. ”
    2. The developer has rated and done in accordance with the specified version.
    3. The requirement for a retail site has changed - the site has changed.
    4. It is the turn of testing the functionality of the subproject implemented by the developer. The implementation did not match what was expected. But! There is an understanding that this was realized even when no changes were planned, because the developer was guided by the specific version of the retail site that was relevant at the time of implementation. And if something needs to be fixed, then this is done as part of a new task, and not bug fixes. So that!


    When I made a presentation on this topic in my company, the first questions were: Are there not too much time wasted just to fill out the requirements? But does it not unreasonably increase the size of the document? And why should the customer read about the version of the requirement?

    So: not much time is wasted, but yes - it is wasted. But for myself, I decided that the benefits of this are worth the small amount of time spent. And yes, it increases the size of the document. To increase it less, I use only those fields that are needed in working on a specific requirement (and try to avoid redundant information). And yes, the customer does not need this entire list (moreover, the developer, writer, tester, too). But until the site starts to change something related to the requirement, or until they are asked to implement (evaluate, test) a specific change (what? - the answer is in the versions of the requirement).

    It is clear that there are some nuances in the work on each project (and indeed the processes are different everywhere), and it is important not to blindly follow any recommendations, but to extract something useful for yourself from them. It is possible to generate some ideas based on the information received. I am for the system used in the first place to solve problems - specific ones that you encounter every day that interfere with your work. And before you implement anything, you need to ask the question “why?”, “What problem will I solve with this?” (Half a minute of philosophy).

    In my work I use Google Docs. There are many advantages to the work (I will not list them here), but from the point of view of organizing the documentation, the first one comes to the convenience of placing links to requirements in the requirements, and the second is a relatively convenient viewing of the history of document changes.
    The system described above is constantly changing and improving (as new problems arise).

    Also popular now: