search

jamesmunns / git_crosstag

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

RFC-1: Should metadata be stored inline or in separate files? #4

Open jamesmunns opened 8 years ago

jamesmunns commented 8 years ago

I believe we will get better usage if metadata is stored separately, because it makes writing and reading the markdown files themselves easier. This is optimizing human usage over tool simplicity. By storing links, etc, outside of the markdown file, we do not clutter the file itself with a new syntax, which may confuse the users. This allows users to write WYSIWYG requirements documents, while still maintaining traceability and linking information.

On the other hand, it may be easier to implement inline requirement links (using something like inlined HTML anchors, e.g. <a name="xtag-sha-abcd..."></a>) from a tool perspective, and it may even be considered 'more usable' for users who want this kind of "in your face" visibility.

I have provided a proof of concept of the first suggestion in my pull request here: https://github.com/jamesmunns/git_crosstag/pull/3

If you think that the second, inline approach is more valid, I would appreciate it if you provide me with either what you think the files will look like before/after processing, or some proof of concept code so I can wrap my head around the other approach. Long day at work today, so my mental facilities are a little lacking.

LudwigKnuepfer commented 8 years ago

I was actually drafting an input/output example with the in-ya-face approach yesterday evening but apparently it was stored in /dev/null.