The spec/doc should be reorganised #330
Comments
|
I 100% agree with all you propose. I would love to try and implement (at least in spirit) a version of https://diataxis.fr/, but your proposal is mostly reorganisation at a higher level. |
The examples provided in the SSSOM/TSV section of the "overview" document are full of errors and would fail the most basic validation by our own tools: - use of `Lexical` instead of `semapv:LexicalMatching` in the `mapping_justification` field (probably a remnant of the time prior to the adoption of the SEMAPV vocabulary); - bogus IRI prefix for the SKOS namespace (missing terminal `#`); - use of a full-length identifier (instead of a CURIE) for `creator_id`. This PR fixes those errors. In addition, it also ensures that the fields are listed in the *recommended order*. It’s not critical but if we take the time to recommend that fields be sorted in a given order, the least we can do is to follow our own advice in our examples. While we are at it, we also add a small note about the requirement for using CURIEs in the SSSOM/TSV format, since that requirement currently does not appear anywhere but is already enforced by `sssom validate`. This is a band-aid until the docs are completely overhauled as part of #330. Co-authored-by: Nico Matentzoglu <nicolas.matentzoglu@gmail.com>
Resolves [#330] - [x] `docs/` have been added/updated if necessary - [x] `make test` has been run locally - [ ] tests have been added/updated (not applicable) - [ ] [CHANGELOG.md](https://github.com/mapping-commons/sssom/blob/master/CHANGELOG.md) has been updated (not applicable) This PR reorganises the documentation, especially the specification part, as suggested in #330. More precisely: * Several bits of informations that were scattered throughout the website are now regrouped on the index page (e.g. “contacts” and “credits”). * The home page gets a “SSSOM at a glance” section to give an immediate glimpse of what the standard is about. * The specification is broken down as follows: * general introduction * specification of the data model * introduction and notes complementary to the LinkML-generated documentation * LinkML-generated documentation * specification of the serialisation formats * SSSOM/TSV format (completely rewritten) * OWL/RDF format (taken from the pre-existing `spec.md` document) * JSON format (currently merely a placeholder, since the JSON format is unspecified #321) The “resources for users” section is left untouched for now. The urgent part was reorganising the _specification_, so that we can start enriching it to make it ready for 1.0.
|
A first round of reorganisation was done in #368, but the user-facing doc (“resources for users”) still probably needs a bit of love. |
|
Do you want to meet for 1 hour of your choice to hack at that together? I am fine to do it, but maybe could avoid some back and forth if we do it face2face. |
|
User-facing documentation is not really my priority for now – I’d rather put the spec in shape for a 1.0 version. Was actually thinking of opening an issue to discuss that (basically the question is: what is still needed before we can call the current state a “1.0” version?), but happy to discuss that e.g. in tomorrow’s “OBO tech support call” (wouldn’t be the first time we hijack it to talk about SSSOM). |
|
Ok perfect! |
|
@gouttegd this is assigned to you, if you want me to handle subitems of this task, let me know. (this item is on milestone 1.0, and I am not too sure of Definition of Done (DoD), and my role in it) |
Right now, the SSSOM website is a bit of a mess.
/sssom/spec/) is a bit of everything:Overall this makes it very difficult for implementers to figure out what and where are the really “normative“ parts of the website. This is of course at least partially due to the fact that the website is clearly a “work in progress“, but also, more fundamentally, because the website somehow tries to be simultaneously a specification for the standard, a documentation of that standard for end-users, a documentation of the reference implementation (
sssom-py), and an academic paper on semantic mappings.More immediately, this makes it difficult for me to figure out where I should put the various improvements to the spec I have been thinking about (such as the propagation of metadata slots #305, the recommendations on backwards compatibility #325, or the recommendations on how to deal with non-standard slots #328).
Therefore I’d like to propose that the website be reorganised so as to clearly separate the specification, the documentation, and the general notions on mappings. I welcome any suggestion for a better organisation, but right now here’s what I’m considering:
Thoughts?
The text was updated successfully, but these errors were encountered: