Possibility to add examples.

[iherman]

We should add the ability to include examples.

Raised on behalf of @msporny

[iherman]

@msporny, @dlongley

I think to do this we should get away from the model you and Gregg did in earlier version of the formal vocabularies whereby the entries appear as part of a big HTML table. Using table would mean squeezing the examples into a table cell, and I am almost sure the horizontal space would not be enough.

Instead, and as a first step, I could rewrite the HTML generation script by putting each term into its own subsection and everything else (description, range/domain, etc) would appear as part of that section. The examples could then be added at the end of the section. In other words, the HTML definition would look more like the CCG document, except that the content would be generated by the script, it would be in RDFa and, of course, the ttl/jsonld versions would also be there. It would also mean to have a very long TOC on the left (just as the CCG) which may look ugly but, in fact, might be better for usability. (Although I believe the level of TOC appearing on the left may be controlled by the respec structure.)

Before I engage into that (it needs more time also due to the RDFa entries that must be reengineered) I wanted to see whether, in principle, you are fine going down that road…

[msporny]

Before I engage into that (it needs more time also due to the RDFa entries that must be reengineered) I wanted to see whether, in principle, you are fine going down that road…

Yes, +1 to it in principle.

The following are just thoughts, no need to act on them, just thinking out loud:

Here's how ActivityPub integrated examples -- all table-based layout. I both like it and think it's too much at the same time: https://www.w3.org/TR/activitystreams-vocabulary/#types -- I really like the "Expected Properties" entries, but feel like there is no easy way to auto-generate those.

I do like the simplicity of the table form we have today. We could try and keep both, but then the document becomes huge w/ duplicated content. I have heard people say that they really liked the examples... and people get really annoyed when the examples become out of date (which most are, at this point). That's the problem about these human-readable vocabularies, they become harmful when they're not maintained well. I don't know how to fix that other than either 1) don't put examples in the document, or 2) keep the examples up to date.

There is a part of me that thinks that we might break each term/entry into a separate .yml file to make it easier to maintain. We could then "bundle" them all together using YAML references OR have the script just pick out every .yml file in a directory and build into the template from there. I'm on the fence about this because we'd be turning something that's simple right now, into something possibly more complex. It doesn't feel worth it to do that at this time.

[iherman]

Before I engage into that (it needs more time also due to the RDFa entries that must be reengineered) I wanted to see whether, in principle, you are fine going down that road…

Yes, +1 to it in principle.

The following are just thoughts, no need to act on them, just thinking out loud:

Here's how ActivityPub integrated examples -- all table-based layout. I both like it and think it's too much at the same time: https://www.w3.org/TR/activitystreams-vocabulary/#types -- I really like the "Expected Properties" entries, but feel like there is no easy way to auto-generate those.

I actually do not really like it. The examples are squeezed into a very narrow place, and with the W3C style which limits the width of the core text that means I have to scroll to the right for them. I think that is bad UI. (Note that I do not blame the AS people; they created their standard before the switch in the W3C document styles.)

As for the auto-generation: I am not even sure what this means. Do you mean deduce it from the YAML file? We cannot because that is not dependent on the domain property; "expected" is not a precise term. The only way would be to get the YAML document yet another field which would be ignored in TTL and JSON-LD and be present in the HTML. But that means that there is a normative-sounding statement that is not present in the TTL and JSON-LD; I do not like that either.

I do like the simplicity of the table form we have today. We could try and keep both, but then the document becomes huge w/ duplicated content.

See above.

I have heard people say that they really liked the examples... and people get really annoyed when the examples become out of date (which most are, at this point).

Yep, that is the danger, and a real one.

That's the problem about these human-readable vocabularies, they become harmful when they're not maintained well. I don't know how to fix that other than either 1) don't put examples in the document, or 2) keep the examples up to date.

... or getting the examples in a separate document altogether, e.g., a primer of sort. Maintaining a primer requires a different skill set than for the vocabulary itself, and maybe by separating them it becomes somewhat easier to maintain, and for people to read.

There is a part of me that thinks that we might break each term/entry into a separate .yml file to make it easier to maintain. We could then "bundle" them all together using YAML references OR have the script just pick out every .yml file in a directory and build into the template from there. I'm on the fence about this because we'd be turning something that's simple right now, into something possibly more complex. It doesn't feel worth it to do that at this time.

I would not go down that road. I do not see what it would really bring us, except for the extra complication in terms of maintenance, coding, etc. (I do not know, for example, whether the YAML parser of node.js would gather those parts automatically and, if not, we would have to do it "by hand"). And I also do not see why maintaining a folder full of small YAML files would make things easier...