search

jamesmunns / git_crosstag

Tool for managing tags within and outside a git repository
MIT License
1 stars 1 forks source link

Define the difference between a "line" and a "requirement" #1

Open jamesmunns opened 8 years ago

jamesmunns commented 8 years ago

For example:

The heading #Compatibility Requirements is not a requirement, it is a heading. It will have subitems, and should still trigger re-reviews of children when updated, however it shouldn't be required to be traced to from a "lower" document (such as the Software Requirements document).

Even more complicated, in the following example, which of these lines is a requirement, and which are just clarification details?

The product will greet the user as such:
* Hello!
    * (No Comma)
* World!
LudwigKnuepfer commented 8 years ago

What I had in mind was this:

  1. The user creates/extends document with blank requirement tags.
  2. The tool fills in the tags.
  3. A requirement ends where the next requirement starts or the document ends.

I did not think about nested requirements. Will do now.

jamesmunns commented 8 years ago

With regards to workflow

One thing that I discovered yesterday is that vanilla markdown doesn't really have a great/standard way to have "invisible" content. It can be achieved through a number of hacks, but something like in-line comments just dont natively exist.

To get around this, I think it makes sense to make an external metadata file that sits next to the markdown (or other type) file. If you check out master, and do the following:

cd source
python3 xtag_engine.py
cd ../examples/unmarked/
cat marketing-requirements.md.xtag

you can kind of see what I'm going for. I started taking it further in the other branch, but fell asleep before I finished. going to try and clean it up this evening.

I really like the idea of "Write the requirements document in pure-markdown, and let the tool handle generation of tags and updates", as opposed to having to know markdown AND xtag syntax. Some kind of xtag knowledge will be needed for filling in references after the fact, but if we can keep it minimal, we allow for less technical people to write valid requirement documents.

With regards to nested requirements

Either way, nested requirements are something to consider. In other tools, I have seen the 'is_requirement' field be user-settable, which is nice, but it means that the tool has to validate the choices (e.g. if you have a requirement, none of its parents or children are requirements).

LudwigKnuepfer commented 8 years ago

Workflow

Personally I don't care if there's shas all over the place.