search

phenopackets / phenopacket-format

26 stars 10 forks source link

normalize documentation #56

Open harryhoch opened 8 years ago

harryhoch commented 8 years ago

Consider reviewing various documentation pages for consistency of tone and coverage. For example, the (https://github.com/phenopackets/phenopacket-format/wiki/Identifiers)[identifiers page] refers to a default JSON-LD context, which might or might not make sense for YAML versions.

Similarly, we might want to help folks bridge JSON-LD vs. JSON-Schema....

cmungall commented 8 years ago

The YAML and JSON are structurally identical and can be trivially interconverted. https://github.com/phenopackets/phenopacket-format/wiki/YAML-and-JSON

But any time you have flexibility like this, it inevitably leads to confusion. We should do more to clarify.

JSON-LD vs JSON-Schema is not a trivial thing to explain. I think it's best handled by explaining these things are meant for different groups of people.

harryhoch commented 8 years ago

@cmungall, understood about YAML and JSON, but this might not be clear to all readers. Would researchers working on human genetics tend to know about these file formats?

+1 to your point about different foci for different audiences. Clear guidance on these topics would be helpful.