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 to read them (as far as possible for technical documentation), and writers to write.
We are talking about the organization of ready-made requirements (the requirements have already been received and formulated, and now they are working with them). And in this context, the requirement is a description of some functionality (in my case, the site), in a language understood by the developer, the customer, the mere mortal, giving an idea of ​​"how this should work."
What is written below is not the ultimate truth, it is only a description of the problems that the development team encounters in working with the requirements on a daily basis and the tools with the help of which they can be solved.
The idea of ​​creating a system for organizing requirements 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 everything is for sale, I’m not afraid of the word - diapers, buckwheat, clothes, tickets), it is also a platform for working with corporate clients, various services, a brand of the zone). All this has its own requirements (the majority have their own business customer), which must be described and somehow stored and processed, and also solved problems. The key ones (of course, there are more, but the list below is the most relevant), which I highlighted for myself:
1. Tasks (analytics, development, testing) are performed by different people, and therefore it is necessary that any non-participant can at any time orient in the requirements and understand what is happening.
')
2. Requirements are constantly updated; → a mechanism is needed that allows for quick and clear changes to be made to existing requirements.
3. Requirements of subprojects refer to the requirements for the retail site → you need a simple and clear organization of documentation and always workable links.
I think the first point does not need detailing - everything is clear.
Requirements are constantly updated.
The seemingly obvious thing: any change on the site, in addition to the block to which the change relates, can have an impact on other functionalities. 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 variable functionality is before our 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 does not even feel anything). But if we have everything in one requirement (and the requirements for the user script, and the data exchange script, and the requirements for the user interface), most likely, this is all related to each other. As a result, making changes only in the system scenario, we touch everything, the change is applied to one big requirement - inconvenient. Therefore, I am in favor of splitting all the requirements. How - I will tell below.
Subproject requirements refer to retail site requirements.
What is the point. I will try to explain with a simple life example.
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, the functionality of the order. (Without the ability to place an order, it will not be an online store, but a catalog.) And this functionality runs like a canvas through the entire site. Here we have screwed on the site the opportunity to purchase goods directly from third-party suppliers - a separate subproject, separate requirements. But here too there is a process for placing an order, which, in general, is the same as for ordinary goods. And what are we doing? Just write: “see requirements for a retail site "- refer. No need to write a new requirement - to spend 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 finished, something is rejected, often the requirements immediately go to the site, bypassing the analyst with its documentation. As a result, the developer develops one, another is written in the documentation, the third is written on the site.
And what happens?
The developer made a “similar to a retail site.” It is time for business testing. What does the customer see? On the main site this way , on his project - in a different way . 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 was exactly the case ? And the assessment was given for such an implementation (the other was not at that time)? As a result, we have to redo it, and this is a new cost, not to mention the discontent of all participants.
Of course, it would be possible within the framework of the project with suppliers instead of a link to simply describe the current functionality on the retail site. But this:
1) duplication (which means if it will be necessary to update the requirements for functionality, this is plus one more point in another document that you need to remember to touch upon updating),
2) even more text in the document (and the documentation cannot be called very entertaining literature - and if it is very large, then you unconsciously begin to experience discomfort),
3) which means that it is necessary to extract information from more text.
You can just say: "look, as done on the site - here as well." But if at the moment between when the implementation was assessed and when the implementation began, something changes on the site, the assessment will no longer correspond to reality.
I identified 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 site works for the site user.
2. System scenarios: what happens inside the site when the user is working with the site - data exchange scenarios, calculations, internal algorithms.
3. User interface requirements: what site user interface object behaves, what is its source, limitations - depending on which element we are talking about (text field, pop-up, drop-down list, frame, etc.) .
First, it is convenient: so the tester, in order to write test scripts, you need to read only user scripts. The business customer agrees on their own and user interface requirements (it is important that it works and looks on the website in accordance with the idea, as it is done inside - it is already decided by technical experts). Similarly, the designer. But analytics, to understand how feasible it is, also needs system scripts. They will also coordinate the interfaces of the site developer with a representative of a third-party system. Etc.
Secondly, when a situation arises that only the internal system scenario changes (what I wrote above), it will be he who will change: there will be no need to get into a big demand, where everything is crammed and rewrite it.
I used to think that it’s cool to keep three types of requirements in three relevant documents (documents “User scripts”, “System scripts”, “Requirements for user interface”), or at least in different sections of the same document. And it seems to be as correct. Consolidation of requirements with this method is done at the expense of requirements codes (I will discuss the requirements codes below). But in conditions of limited time, it is easier for me to start all three types of requirements in one place - so that it is at hand.
So I’m for flexibility, and not for blindly following the rules - you need to choose the option that is convenient (while forgetting that both developers, and testers, and people without a corresponding technical background read the requirements). Taking into account the possible consequences (maybe now it is better to put a little more effort, but then they will need less?).
Secondly, each requirement must have its own individual code .
Well, it is quite understandable and logical, so everyone does. I went a little further in this question - in the requirement code I try to reflect: links, versions, some additional data:
It is more correct to use " SUC " - system use case instead of " TECH ", but the customer may misinterpret (somehow we were already asked to rename the requirement code, because the abbreviation turned out to be BR ED).
The fourth column - CR - this is exactly the “some additional data”. In this case, the data needed by the manager to understand whether a change in demand was made within the framework of the main scopa or for separate money.
And the version is exactly what will allow us to beautifully get out of the situation when it is done “similarly to the main site”, and the main site has changed by the time of testing. Next, I will tell you how, in my opinion, it's cool to draw up requirements, in the same place - about versions.
As for the rest, in the picture, it seems to me, everything is reflected quite clearly.
Third: the requirements .
I do it like this:
I already wrote about the Requirement Code a little higher.
Related Requirements put requirements codes that describe the same functionality, but from the point of view, for example, of data exchange (what I mentioned when I called for separating requirements into three types), respectively, the requirement code of the related requirements should be the same, except for the part denoting type. Names can also be different.
Child requirements are extensions of existing requirements (in the example, this is an iFrame requirement that becomes available within the described requirement). You can add the "Parental Requirement" field, where, accordingly, the requirement code will be displayed, the extension of which is the described requirement (phew!).
The ERP fields and the Payment System are optional, they are needed only if the ERP and Payment Systems 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 coordination stage: when representatives of different systems have to agree on a document, they don’t have to read the entire document, it’s enough to confine themselves to the requirements where their work is affected.
You can add the “Layouts” field here, if any, and display a link to them (the developer will be grateful). You can add a link to the task in Jira (Redmine, etc.) - in general, anything you wish.
Next comes the Versions section - in my opinion, one of the key blocks.
How to work with him and what is its essence?
When the demand change comes, then:
1) The requirement is changed by the writer (logical)
2) A new line is created in the "Versions" section, where:
When we refer to a requirement from another document (subproject), we already indicate the version of the requirement to which we refer. Do you feel? Do you feel?
When in my company I gave a presentation on this topic, among the first questions were: But isn’t too much time spent just to fill out the requirements? But does this 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 spent, but yes - it is wasted. But for myself, I decided that the benefits derived from this are worth this small amount of time spent. And yes, it increases the size of the document. In order to increase less, I use only those fields that are needed in the work on a specific requirement (and I try to avoid redundant information). And yes, the customer does not need this entire list (moreover, the developer, the writer, the tester, too). But until the site starts changing something related to the requirement, or until it is asked to implement (evaluate, test) a specific change (which one is the answer in the versions of the requirement).
It is clear that the work on each project has its own nuances (and indeed the processes are different everywhere), and it is important not to blindly follow any recommendations, but to extract something useful from them. Perhaps on the basis of the information received to generate their own ideas. I am in favor of the system being used to solve problems in the first place - specific problems that you encounter daily, which interfere with your work. And before introducing something, you need to ask the question “why?”, “What problem will I solve with the help of this?” (Half a minute of philosophy).
In my work, I use Google Docs. There are many advantages of work (I will not list them here), but from the point of view of organizing documentation, the first thing that comes to mind is the convenience of placing references to the requirements in the requirements, and the second is a relatively convenient viewing of the document change history.
The system described above is constantly changing and improving (as new problems appear).
We are talking about the organization of ready-made requirements (the requirements have already been received and formulated, and now they are working with them). And in this context, the requirement is a description of some functionality (in my case, the site), in a language understood by the developer, the customer, the mere mortal, giving an idea of ​​"how this should work."
What is written below is not the ultimate truth, it is only a description of the problems that the development team encounters in working with the requirements on a daily basis and the tools with the help of which they can be solved.
Where did the need for all this come from? Why is this all about?
The idea of ​​creating a system for organizing requirements 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 everything is for sale, I’m not afraid of the word - diapers, buckwheat, clothes, tickets), it is also a platform for working with corporate clients, various services, a brand of the zone). All this has its own requirements (the majority have their own business customer), which must be described and somehow stored and processed, and also solved problems. The key ones (of course, there are more, but the list below is the most relevant), which I highlighted for myself:
1. Tasks (analytics, development, testing) are performed by different people, and therefore it is necessary that any non-participant can at any time orient in the requirements and understand what is happening.
')
2. Requirements are constantly updated; → a mechanism is needed that allows for quick and clear changes to be made to existing requirements.
3. Requirements of subprojects refer to the requirements for the retail site → you need a simple and clear organization of documentation and always workable links.
I think the first point does not need detailing - everything is clear.
Requirements are constantly updated.
The seemingly obvious thing: any change on the site, in addition to the block to which the change relates, can have an impact on other functionalities. 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 variable functionality is before our 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 does not even feel anything). But if we have everything in one requirement (and the requirements for the user script, and the data exchange script, and the requirements for the user interface), most likely, this is all related to each other. As a result, making changes only in the system scenario, we touch everything, the change is applied to one big requirement - inconvenient. Therefore, I am in favor of splitting all the requirements. How - I will tell below.
Subproject requirements refer to retail site requirements.
What is the point. I will try to explain with a simple life example.
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, the functionality of the order. (Without the ability to place an order, it will not be an online store, but a catalog.) And this functionality runs like a canvas through the entire site. Here we have screwed on the site the opportunity to purchase goods directly from third-party suppliers - a separate subproject, separate requirements. But here too there is a process for placing an order, which, in general, is the same as for ordinary goods. And what are we doing? Just write: “see requirements for a retail site "- refer. No need to write a new requirement - to spend 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 finished, something is rejected, often the requirements immediately go to the site, bypassing the analyst with its documentation. As a result, the developer develops one, another is written in the documentation, the third is written on the site.
And what happens?
The developer made a “similar to a retail site.” It is time for business testing. What does the customer see? On the main site this way , on his project - in a different way . 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 was exactly the case ? And the assessment was given for such an implementation (the other was not at that time)? As a result, we have to redo it, and this is a new cost, not to mention the discontent of all participants.
Of course, it would be possible within the framework of the project with suppliers instead of a link to simply describe the current functionality on the retail site. But this:
1) duplication (which means if it will be necessary to update the requirements for functionality, this is plus one more point in another document that you need to remember to touch upon updating),
2) even more text in the document (and the documentation cannot be called very entertaining literature - and if it is very large, then you unconsciously begin to experience discomfort),
3) which means that it is necessary to extract information from more text.
You can just say: "look, as done on the site - here as well." But if at the moment between when the implementation was assessed and when the implementation began, something changes on the site, the assessment will no longer correspond to reality.
And what to do?
I identified 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 site works for the site user.
2. System scenarios: what happens inside the site when the user is working with the site - data exchange scenarios, calculations, internal algorithms.
3. User interface requirements: what site user interface object behaves, what is its source, limitations - depending on which element we are talking about (text field, pop-up, drop-down list, frame, etc.) .
First, it is convenient: so the tester, in order to write test scripts, you need to read only user scripts. The business customer agrees on their own and user interface requirements (it is important that it works and looks on the website in accordance with the idea, as it is done inside - it is already decided by technical experts). Similarly, the designer. But analytics, to understand how feasible it is, also needs system scripts. They will also coordinate the interfaces of the site developer with a representative of a third-party system. Etc.
Secondly, when a situation arises that only the internal system scenario changes (what I wrote above), it will be he who will change: there will be no need to get into a big demand, where everything is crammed and rewrite it.
I used to think that it’s cool to keep three types of requirements in three relevant documents (documents “User scripts”, “System scripts”, “Requirements for user interface”), or at least in different sections of the same document. And it seems to be as correct. Consolidation of requirements with this method is done at the expense of requirements codes (I will discuss the requirements codes below). But in conditions of limited time, it is easier for me to start all three types of requirements in one place - so that it is at hand.
So I’m for flexibility, and not for blindly following the rules - you need to choose the option that is convenient (while forgetting that both developers, and testers, and people without a corresponding technical background read the requirements). Taking into account the possible consequences (maybe now it is better to put a little more effort, but then they will need less?).
Secondly, each requirement must have its own individual code .
Well, it is quite understandable and logical, so everyone does. I went a little further in this question - in the requirement code I try to reflect: links, versions, some additional data:
It is more correct to use " SUC " - system use case instead of " TECH ", but the customer may misinterpret (somehow we were already asked to rename the requirement code, because the abbreviation turned out to be BR ED).
The fourth column - CR - this is exactly the “some additional data”. In this case, the data needed by the manager to understand whether a change in demand was made within the framework of the main scopa or for separate money.
And the version is exactly what will allow us to beautifully get out of the situation when it is done “similarly to the main site”, and the main site has changed by the time of testing. Next, I will tell you how, in my opinion, it's cool to draw up requirements, in the same place - about versions.
As for the rest, in the picture, it seems to me, everything is reflected quite clearly.
Third: the requirements .
I do it like this:
I already wrote about the Requirement Code a little higher.
Related Requirements put requirements codes that describe the same functionality, but from the point of view, for example, of data exchange (what I mentioned when I called for separating requirements into three types), respectively, the requirement code of the related requirements should be the same, except for the part denoting type. Names can also be different.
Child requirements are extensions of existing requirements (in the example, this is an iFrame requirement that becomes available within the described requirement). You can add the "Parental Requirement" field, where, accordingly, the requirement code will be displayed, the extension of which is the described requirement (phew!).
The ERP fields and the Payment System are optional, they are needed only if the ERP and Payment Systems 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 coordination stage: when representatives of different systems have to agree on a document, they don’t have to read the entire document, it’s enough to confine themselves to the requirements where their work is affected.
You can add the “Layouts” field here, if any, and display a link to them (the developer will be grateful). You can add a link to the task in Jira (Redmine, etc.) - in general, anything you wish.
Next comes the Versions section - in my opinion, one of the key blocks.
How to work with him and what is its essence?
When the demand change comes, then:
1) The requirement is changed by the writer (logical)
2) A new line is created in the "Versions" section, where:
- Version code - code of the requirement being changed plus the date of version creation;
- The source - where we got this change (from the letter, in the correspondence, the task, etc.) - is useful when it is necessary to figure out why what has changed and who and at what moment became the initiator;
- The new value is what has changed in the requirement.
When we refer to a requirement from another document (subproject), we already indicate the version of the requirement to which we refer. Do you feel? Do you feel?
- The developer in the requirements of the subproject read: “see version of the requirements for the retail site.
- The developer has evaluated and made in accordance with the specified version.
- The requirement for a retail site has changed - the site has changed.
- It’s the turn of testing the developer’s functionality of the subproject. The implementation did not coincide with what was expected. But! There is an understanding that this was realized even when no changes were planned, because the developer was guided by a specific version of the retail site that was relevant at the time of implementation. And that if something needs to be corrected, then this is done within the framework of a new task, and not the correction of bugs. So that!
Conclusion
When in my company I gave a presentation on this topic, among the first questions were: But isn’t too much time spent just to fill out the requirements? But does this 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 spent, but yes - it is wasted. But for myself, I decided that the benefits derived from this are worth this small amount of time spent. And yes, it increases the size of the document. In order to increase less, I use only those fields that are needed in the work on a specific requirement (and I try to avoid redundant information). And yes, the customer does not need this entire list (moreover, the developer, the writer, the tester, too). But until the site starts changing something related to the requirement, or until it is asked to implement (evaluate, test) a specific change (which one is the answer in the versions of the requirement).
It is clear that the work on each project has its own nuances (and indeed the processes are different everywhere), and it is important not to blindly follow any recommendations, but to extract something useful from them. Perhaps on the basis of the information received to generate their own ideas. I am in favor of the system being used to solve problems in the first place - specific problems that you encounter daily, which interfere with your work. And before introducing something, you need to ask the question “why?”, “What problem will I solve with the help of this?” (Half a minute of philosophy).
In my work, I use Google Docs. There are many advantages of work (I will not list them here), but from the point of view of organizing documentation, the first thing that comes to mind is the convenience of placing references to the requirements in the requirements, and the second is a relatively convenient viewing of the document change history.
The system described above is constantly changing and improving (as new problems appear).
Source: https://habr.com/ru/post/282311/
All Articles