Review Process for Customers

[kreuzberger]

Hi!

TLDR: What is the workflow to ease needs reviews with customers

Using needs for requirements and test case handling works perfect during developing our project in the company.
Generation of Documents and Specifications for customer review is also good.

But how is it intended to have a "feedback" from the customer? Currently we could give him pdf documents where he can make annotations. I think giving him "the plain ReST files" for changing is not intended.

In a technical aspect we can give him json files to add changes directly (and for example change the status of the need). (See needs-viewer app?)

Thinking of your vscode plugin for needs, is there a possible way to have "merges" or change handling (annotations) for these issues in a "comfortable" way?

[danwos]

Copy of my comment in #943:

This is not an easy topic.
The viewer may be a solution. Another one is to exchange the data in technical Format like ReqIF, which can be im/export also for IBM Doors and other tools.

So the need object gets transferred to a customer system, handled/updated there and exported again.
But this process is often very project and tooling specific. So I have no generic solution.

[kreuzberger]

I think it was not so clear what i intended. Your are right, technical import of requirements is one thing, its tooling and project specific.
I would describe more clearly what i mean:

1. I have the ownership of the requirements. I am responsible for creating/deletion/changing.
2. I generate a requirements document that i do send to the customer for review, cause i have no possibility to do this directly on the code base. I would prefer html delivery, second option is pdf.
3. Review now means e.g. the customer as to "accept" the requirements as ok, or just annotates a requirement e.g. due to typos or anything else.

Question: How can we support those annotations to come back to me?
Current: The customer has to write manually down changes in a separate document. He cannot annotate directly in the html. He cannot bulk change status of some or all requirements.

Suggestion: Customer has the posiblilty to "annotate" in html the requirements "directly". The Data is stored somewhere in the html tree (e.g. in a needs.json file, needs.diff.json file or something else). Seems to be something the "viewerApp" could do. He sends me the "annotated" file back and i can now load this in vscode, see annotated requirements in the needs explorer view, jump to them and can take over changes, status etc.
OR i manually merge the files, but merging is possible cause it is the same format.

I hope this describes more clearly my intentions.

[danwos]

Ok, got it now. Thanks for the details.
This is definitely something for an additional solution, where some user interface support is needed.
Maybe by a JS-solution in HTML, or by a VsCode extension.

Another idea is to maybe support a standardized format like ReqIF.
Then the customer can use any requirement tool and you still can use Sphinx-Needs.
Mhh, but the returned ReqIF-file would still not update your rst-files. But at least diffs could be shown in a VsCode extension.

But nothing of this is yet available and would need some weeks to get implemented.

[kreuzberger]

Just need a way to get the annotations back in a standardized way, I will have a look at the ReqIF format. Automated update of rst files is not required/intended, integrations have to be done manually and checked. The only exception would be e.g. bulk changes of requirment status updates (e.g. customer is setting them all to "accepted" state without any other changes), but this is also an easy "search and replace" operation.

Main intention of the issue was to find out what solutions / best practices / experiences others have already made.