Update README and CONTRIBUTING with markdown format

[goneall]

We're getting requests on the Gitter channel for more information on the markdown format.

The spec parser documents the format grammar, but I couldn't find any context other than the property template and vocabulary template in core.

[goneall]

@zvr - If we don't have any docs available, I can make an attempt to write it up if you are available to review. Just let me know.

[MordodeMaru]

Happy to help with this, @goneall

[zvr]

We have nothing written down, sorry.

And the spec-parser evolves constantly, so the documentation you pointed to may or may not be correct. The only source of truth is the actual code, I'm afraid.

Once we finalize the format, we should make an effort to document it, obviously, but right now we're pressed to adapt it to our ever-changing needs (cf. individuals ;-)).

[goneall]

Moving to 3.0

[aamedina]

What is the motivation for using this markdown format over specifying things with Turtle that can be edited both with any text editor but also graphically via Protege? People contributing to the spec, if they are unfamiliar with RDF/SHACL would have to learn what all of the "terms" in the markdown format mean in order to contribute thoughtfully to any definition.

By declaring the prefixes for the file at the beginning like in Turtle users can see what namespaces are in scope at any profile and look up corresponding terms when necessary for documentation (a process which could be automated using Protege as well).

I suspect this process may present a bottleneck to meaningful contribution.

[goneall]

What is the motivation for using this markdown format over specifying things with Turtle that can be edited both with any text editor but also graphically via Protege?

In general terms, we have a lot of contributors to the spec who are not RDF / OWL / SHACL savvy, so we devised a format that was acceptable to that community yet allowed those of use more comfortable with RDF / OWL / SHACL to generate and review the more precise schemas. The format was the result of very long discussions with may contributors with different perspectives.

BTW - In my workflow, I typically review the generated model.ttl file using protege then update the markdown files when needed.

[aamedina]

Yeah, I can imagine how complicated marketing RDF to others is. I can figure it out, but I can see how this will be a perpetual problem the more expressive people want to get with properties.

BTW if you want to look at some of my TTL while I explore/learn the SPDX 3 model: https://github.com/aamedina/ssvc/tree/main/resources/spdx

I am trying to figure out the best way to go about transferring changes I make in the model here (I am importing the model into Datomic and querying with datalog, mapping SPDX 2.3 RDF I have to the new model), so I need a "source" that is relatively stable for my workflow so I will probably be pulling changes you make into that until things finalize.

[goneall]

We probably won't get this documented in time for 3.0, but still would be nice to have for future contributors.

Moving to 3.1.

[bact]

@aamedina @goneall @zvr with #867 already merged, does this issue considered fixed and can be closed?

[goneall]

@aamedina @goneall @zvr with #867 already merged, does this issue considered fixed and can be closed?

@bact - Agree - I'll go ahead and close it. If anyone see any additional need for documentation please open a new issue or PR.