Last episode needs more discussion about what to include

[allegravia]

Mateusz and I think we should discuss if we are full happy with the current content of this episode. - - Can documentation be sort of metadata? More explanation is needed about the difference between documentation and metadata (e.g., by providing examples).

• Should we add a description on how to add metadata "manually" (i.e. not using a platform/registry)? Should we describe the different ways to add metadata and tell that registries are one of those?
• We think we should provide more examples of metadata (e.g., HTML metadata tags, Package Metadata in R, CodeMeta json-ld) and explain how metadata make software more discoverable (in these examples, e.g. HTML pages by Google).
• Some concepts in the episode should be made clearer (e.g. the paragraph on controlled vocabularies).

[orchid00]

I would like to add these links to collaborate with the metadata-episode and continue this discussion

• https://www.ands.org.au/working-with-data/metadata
• http://rd-alliance.github.io/metadata-directory/

[orchid00]

About this topic "Can documentation be sort of metadata? More explanation is needed about the difference between documentation and metadata (e.g., by providing examples)."
The team working on contributions had also this discussion is Documentation part of the guidelines for contribution?
We have defined that documentation is all about how the software works focusing on the user.
We also discussed that documentation is the "whole package" the point of reference for all, and as such it should contain at least links to all the recommendations.
A link to the public repo, a link to the licence, a link to the contributions guide, and a link to metadata, either a file or a public metadata repository where the metadata has been registered.

[orchid00]

there is also a clear visual about documentation and metadata here, page 7: https://drive.google.com/file/d/1LEYLkTmPvUfamYDzMfQfX1SsHFl99ZPa/view