Limitations

With time we've noticed that we had recurrent feedback, so we would like to set expectations by summarizing the limitations of Requirement Yogi.

Permissions

• Requirements belong to a space. You can view them if you can view the space; You can edit them if you can edit pages on the space.

• Tagging the row of a table as a requirement "exports" its text to the space. That means ANYONE with view permissions on a space will be able to see the requirement. In other words, we don't take into account page-level restrictions.

• Requirements can be seen in Jira. If a user is able to create a link from Jira (they require OAuth permissions to view the requirement for that), then the text of the requirement will be brought to Jira.

Formatting

• We simplify the HTML of the requirement. The goal is to avoid having "block" elements (paragraphs, lists, tables) so that it doesn't disturb the layout when displaying the title of a requirement in search results or other places. We also remove a lot of CSS formatting since it can't be displayed the same way in Jira.

• We don't render dynamic content.

• Images aren't copied in a binary way to the requirement. We only keep a URL of the images:

  • If you swap the image at the end of the URL, the image will be swapped in the requirement. This is particularly relevant when a requirement is baselined, since you don't always expect the image to change.

  • If you display the requirement in Jira, the image will be a URL to Confluence. It will appear broken, unless you are logged in to Confluence and have the permissions to view the image.

  • Therefore we don't recommend images in requirements.

  • If you use Requirement Yogi for, say, an architecture document or a technical drawing with lots of images, the best way is to use our API to create an extension, so that you can manage requirements inside of your specialized software.

• Since space administrators can delete page versions, baselined requirements may not always have a page version to link to. In such cases, we link to the closest page version. Note that administrators can also delete baselines and all their requirements anyway.

• We don't have a validation engine for requirements. The upside of the software is that users are very free to enter the text they want; The downside is that it is still difficult to ensure they are all formatting their requirements the same way.

Diff

• The current diff is limited to 600 requirements (=5% of the global limit, which you can configure).

• This is not enough for large customers with 12k requirements in baselines,

• It is a difficult problem to solve, but not impossible; We are hoping to solve it one day.

Requirement keys

• Before RY 3.0:

  • We only accept a-z A-Z 0-9 and the three characters: . - _

• After RY 3.0:

  • Those characters are forbidden: / \

  • We haven't noticed any character that caused an issue, but if we hear about it, we will write the inventory here,

  • Requirement numbers can only reach +9223372036854775807. If you need higher numbers, please add another character in the middle.

• The reason is that we carry requirement keys in the URLs, and dealing with UTF-8 in URLs is difficult,

• Please avoid lone words for keys. Some customers use RY as a glossary, translating acronyms... That is not the intended purpose of Requirement Yogi.

• Unicity is guaranteed when inserting manually. There are corner cases where you may create duplicate requirements in a space (if you use an external plugin to create pages, for example); Requirements will appear in bright red with an error message to tell you to choose which one is the definition.

• Keys are unique per space.

• You can always create links across spaces by pasting the canonical URL of a requirement. You can only create links across spaces manually by searching in the Requirement macro, if you haven't ticked the option "Isolate spaces".

What to write in requirements

• This is more of a functional question, but often asked.

• Please design your workflow so that the developers click on the requirements and view them "in context". They will always be better formatted, with more contextual information. There is some loss in the textual content, the great value of RY is to link back to the correct section in the Confluence page.

• Please keep dynamic information in Jira (Stories, bugs, change requests, etc.) and static information in Confluence (specifications, how the designed system should behave etc.). It is not an excellent practice to write requirements which are actually "Stories" in Confluence, and trying to copy them over to Jira.

Traceability matrix

• The traceability matrix is paginated and can easily display 600 rows per page, on dozens of thousands of results,

• However, we don't support retrieving "too much" data from Jira, and pages need to be shorter as the number of Jira columns grow,

• Customers face problems when they want to export their entire matrix to Excel, which means it takes more than 2 minutes to extract the data from Jira. Requirement Yogi is not designed to pull the entire status of a project from Jira through the little pipe of communication between the apps.

• Workaround: Please investigate using EazyBI in Jira and retrieve the details of the requirements using our REST API.

• Also, we don't support calculated fields. It means we can't show the percentage of child requirements which match a given rule (for example, the % of requirements where the status is "OK", for the most usual usecase of tracking a project).

• As a conclusion, Requirement Yogi is designed to help structure the free text and track the requirements, but we are not a good project planning tool, and you would need an external BI engine for the project planning part.

Administration

• There is a queue of messages in Confluence and in Jira, that are transmitted to each other. This is designed to ensure that a user who doesn't have permissions in Jira can modify requirements in Confluence and have Jira updated.

• When installing the product, you must enter a username in both products for this queue.

Images

• Since we only save the HTML of the requirement, and the HTML contains a URL to the image and not the image itself, someone could change the image at the end of the URL, for example by uploading a new version of this image in Confluence.

• Because of this, images in baselines are not guaranteed, since images can be swapped with other ones,

• Because of this, Jira will attempt to display the image, but may fail if the user is not conneted to Confluence, or if the applink between Confluence and Jira doesn't allow cross-domain images.

The 1-to-1000 issue

• We don't support links from 1 requirement to 1000 dependencies, or 1 Jira issue to 1000 requirements.

• We expect requirements to be linked to 3 to 20 dependencies.

• We expect requirements to have 10 to 50 properties.

• The problems you would meet would be:

  • The hard limit in Jira,

  • In the traceability matrix, the backend has to load all the dependencies despite only showing the first page (the size depends on your choice, let's say 600 rows).

  • The popup in Confluence will be long to load, and the contents of all requirements are preloaded when the page is loaded.

Workflows and validation

• Requirements don't have a status.

• Customers manage the status by using a STATUS macro, and changing the text and colour manually.

• Customers also use EDM "Easy Dropdown Macro" to have a dropdown as a status.

• The drawback is, there is no validation of the permissions associated with the status change.

• The other drawback is, people do spelling mistake, and they can type "Valiid". We are planning on introducing a rules engine in the medium term. As usualy, please don't count on it until it is done and published.

Branching

• We can't support editing several versions (the "1.x and 2.0 problem") of the requirements in parallel.

• For example, you may have version 1.x of the requirements, for which you are performing little changes/bugfixes for the current customer, and you may be working in parallel on version 2.0 of your product, in which you are making major changes. You may even expect to perform a change in 1.x and merge it into version 2.0. This is extremely difficult to support, and we are not doing it yet.

• Although the third-party plugin Scroll Versions is able to maintain several versions of the pages, we can't index those pages. We'll only ever index the currently-published version of those pages.

• The only workaround is to have two spaces, which act like two separate versions of the requirements, and copypasting the text manually across spaces.

Inheritance

• Some customers have 1 product, with 10 customizations for 10 customers.

• We don't support that.

• No, really, for the moment, customer who have tried haven't been successful. We have plans in our cave, we'll do it: Wait for us.

Hoping this clarifies any question about the limitations of the product, we will update this list if other recurrent questions come up.