Where to put the examples?

[jneubert]

There has been several mentions of examples in different issues. Everybody seems to agree that (more) examples are valueable, but it is an open issue where to put them.

@tombaker argued in https://github.com/dcmi/usage/issues/16#issuecomment-394088043:

I'm generally inclined not to put examples into the main vocabulary specification. If we did include them, however, we would need to give some thought to how they would be formatted in the HTML and RDF representations of DCMI Metadata Terms.

If not included in the vocabulary specification, an alternate option could be a revised and extended version of the Dublin Core Usage guide, interlinked on a section level from the respective term definitions.

This issue has been created to have the general discussion in one place.

[tombaker]

@jneubert Thank you for reading my mind! I was about to create this issue myself especially since, on my most recent pass through the draft ISO 15836-2, I was noticing "example" blocks that I had not yet flagged as issues.

I see three possible ways to handle these:

1. Create a new category, both in DCMI Metadata Terms and in ISO 15836-2, specifically for examples. This would create new formatting requirements for the DCMIMT document, for instance: string examples could be formatted in Markdown as code blocks.
2. Allow ISO 15836-2 to include examples (subject to Usage Board approval) but not include them in DCMI Metadata Terms.
3. Systematically leave examples out of scope for DCMIMT, though in scope for the expanded usage notes that Paul and I want to include in the planned documentation generator.

I like option 3 the best, could live with option 2, and would prefer not to make the basic vocabulary specification heavier with examples that really more properly belong in expanded usage sections or in application profiles.

[kcoyle]

I, too, prefer #3. Examples are great, but unless they are fairly extensive they can mislead. They also at times need further explanation.

[tombaker]

@jneubert What you suggest for the usage guide is precisely what Paul and I have in mind. Basically, we'd like to split the usage examples into separate files, per-term, then:

• on the one hand, use a Hugo template to reassemble the examples into a usage guide
• on the other hand, use Hugo templates to merge the definition from DCMI Metadata Terms with the usage examples into a separate Web page about each term

The separate files with usage examples, per term, could then be available for pull requests to illustrate how the terms are used in various implementations.

[jneubert]

@tombaker, @paulwalk I think that's an excellent approach.

Pull requests for the "non-normative" sections could allow us to improve and extend examples where they turn out as mis-leading, add further explanation etc., as @kcoyle mentioned, while leaving the standard itself untouched.

[juhahakala]

Leaving examples out of the standard is fine with me, if there is an up-to-date resource such as usage guide or usage notes which contains examples the Dublin Core specification can cite.

Examples can be misleading, but not giving sufficient guidance may be even worse option than providing well chosen examples on recommended / correct usage of the /terms/ properties. There is a reason why both cataloguing rules and MARC format contain a lot of examples. MARC examples "work" well because the format + cataloguing rules provide more than sufficient amount of background information. With Dublin Core it is not possible to support the users in the same way, but our ambition level does not need to be that high either.

[jneubert]

@juhahakala , when you say

Leaving examples out of the standard is fine with me, if there is an up-to-date resource such as usage guide (...)

this is perhaps a mis-understanding: What @tombaker suggests in https://github.com/dcmi/usage/issues/37#issuecomment-397211984, is (if I didn't get this wrong) having per term one source file for the usage examples, which is pulled into the DC Terms definitions as well as into the usage guide via a templating mechanism. So we would have exactly the same examples in both places.

[tombaker]

In other issues, we have opted to keep examples, so the question has been decided for the purposes of the ISO draft. For DCMI Metadata Terms we still have the option of putting examples into separate, crowdsourced files, per term, for display on per-term Web pages or for aggregation into a user guide.

[tombaker]

Reopening.