Functional requirements: extract first two document fragments

[stanislaw]

Summary of the changes:

• Both documents now have their own folders.
• The grammar for the Zephyr Functional Requirements document is extracted to a separate file functional.sgra.
• Two fragments documents are created from the sections "File System" and "Tracing".

StrictDoc 0.0.53 version is needed for this changeset to work.

Signed-off-by: Stanislav Pankevich s.pankevich@gmail.com

[stanislaw]

I really like this approach, also to handle the grammar in a separated file. This makes it easier to concentrate on a topic better.

I have rebased the PR, it is green again. Please let me know if anything else has to be done.

[nashif]

what exactly is the purpose of having numbers in the folder names? why is the folder called 01_high_level_requirements? We know those are requirements, that is the whole purpose of this repo, so could we just name those folders

• high_level
• functional

insteadf of this lengthy name?

[stanislaw]

what exactly is the purpose of having numbers in the folder names? why is the folder called 01_high_level_requirements? We know those are requirements, that is the whole purpose of this repo, so could we just name those folders

* high_level

* functional

insteadf of this lengthy name?

There is no specific reason to have the documents named this way. Could you suggest how the folder names and the root document names should be called? Do you mean this?

docs/high_level/high_level.sdoc
docs/functional/functional.sdoc

Separate folders for both documents seems to make sense now because the fragment documents are being introduced for the functional requirements document.

From my experience with the regulated space industry is that the documents usually have unique UIDs, sometimes directly embedded to their titles, but these UIDs do not have to be in the file name. My understanding is that the document metadata and numbering convention will come from @nicpappler as a functional safety manager when the document package structure is agreed on.

[stanislaw]

@nashif and others, please check again. It took some extra time to adjust the JSON export to skip the included documents' standalone files.

[stanislaw]

Looking good to me also the renaming is according the consensus from the focus group ( as far as I saw it from the agenda).

Thanks for the review!

Just one question about the sub-file naming is there a reason behind the _ of the files or is needed?

The only reason I added the underscore is to highlight the difference between the including document and the included fragment-documents. My reasoning was that it would be easier to visually distinguish between index.sdoc and many new fragment documents that will appear if this gets merged (expecting at least 15-20 fragment files). All _-files would be sorted together, visually separated from the main index file.

If this is confusing, I can remove the underscores. Can do it either way, let me know.

[simhein]

Looking good to me also the renaming is according the consensus from the focus group ( as far as I saw it from the agenda).

Thanks for the review!

Just one question about the sub-file naming is there a reason behind the _ of the files or is needed?

The only reason I added the underscore is to highlight the difference between the including document and the included fragment-documents. My reasoning was that it would be easier to visually distinguish between index.sdoc and many new fragment documents that will appear if this gets merged (expecting at least 15-20 fragment files). All _-files would be sorted together, visually separated from the main index file.

If this is confusing, I can remove the underscores. Can do it either way, let me know.

Thanks for the clarification. I would prefer to remove the _ upfront from the sections because it might lead to confusion that these files might be temporary or not that important.

[stanislaw]

Looking good to me also the renaming is according the consensus from the focus group ( as far as I saw it from the agenda).

Thanks for the review!

Just one question about the sub-file naming is there a reason behind the _ of the files or is needed?

The only reason I added the underscore is to highlight the difference between the including document and the included fragment-documents. My reasoning was that it would be easier to visually distinguish between index.sdoc and many new fragment documents that will appear if this gets merged (expecting at least 15-20 fragment files). All _-files would be sorted together, visually separated from the main index file. If this is confusing, I can remove the underscores. Can do it either way, let me know.

Thanks for the clarification. I would prefer to remove the _ upfront from the sections because it might lead to confusion that these files might be temporary or not that important.

As discussed, the underscores have been removed. Please check again.