Documentation is not enjoyable to read

[cthoyt]

Despite the advantages of using LinkML to define the SSSOM datamodel and autogenerate this page https://mapping-commons.github.io/sssom, I do not enjoy reading this page.

As an developer who wants to produce SSSOM, I would like a table that says what are the columns I need to / could put in my TSV file and explanations on what needs each field is. I do not want to get this conflated with stuff that should appear constant in every row and is more logically a property of the entire file itself, like "license" and "documentation". I also don't care at all about the jargon used in LinkML and more generally for metamodels like "classes" and "slots", and this only serves to confuse/demotivate me.

Somehow this should either be the first page in the standard, or there should be a massive, impossible-to-miss link pointing to such a table

[graybeal]

I agree, though I think this is a fine approach/document for the specification details.

I'm thinking a thoughtfully formatted example (with overlaid commentary) would be a better starting point than dropping someone directly into the standard.

And a brief description (overview) before that of what they will be seeing would be even more helpful.

I apologize for not offering to do this, but I will offer the example of SKOS Play's Excel format in a Google sheet: https://docs.google.com/spreadsheets/d/19cnChnzukBQv5uvPxmyWB9am_YvnONVrvjm87dhpT34/edit#gid=1198865354 (as previously noted I find this format powerful and compelling. end of advert.)

[matentzn]

I think you are totally right with everything you say, and it these pages are entirely customisable using jinja templates.

With the current resources I cannot prioritise this right this moment, but we will do it before the Padua workshop during a major revision of the docs.

[jamesamcl]

I went to the docs trying to find out what I could put in a mapping field (specifically I wanted to know if an IRI was ok or whether it always had to be a CURIE like in the examples).

I scrolled down the page. Thankfully I'm reasonably familiar with LinkML so I know that what the docs call a "slot" corresponds to a column. So I looked in the slots for "subject_id", but they were arranged alphabetically so I had to do some scrolling through all the other random optional slots (there's nothing to indicate what's optional or otherwise from the table).

Finally I found subject_id, and I see this:

Ok, so can I put an IRI in this field? I click "EntityReference" which is apparently the range.

I still (as a consumer of the docs who just wants to create a TSV file) have absolutely no idea what I can put in this field. It looks like any string or maybe a URI because rdf:Resource?

It's clearly not a good introduction to SSSOM, and I actually disagree with @graybeal that this is a good representation of the spec because even as someone trying to implement the spec I can't work out what I can put in the field!

[graybeal]

Yes, let me clarify my earlier statement.

I think using auto-generation to produce documentation can work very well. This documentation could be more tuned to the naive user.