Call for missing documentation

[alamers]

As we are approaching version 1.0, we should look at the documentation as well. This ticket is mostly a call for missing documentation: what do you think we should add to the docs?

[alamers]

We should explain the use of identifiers / schemes and give examples. There is already a first start: https://github.com/adewg/ICAR/blob/master/location-scheme.md

[alamers]

As mentioned in the call just now (forget who mentioned it...): we should mention the use of these tickets more prominently so people can engange with the workgroup via this way as well.

[alamers]

Suggestion was to have a summary of all available messages on the wiki, with a quick summary and how they relate to each other (e.g. what is the difference between a milking visit and a lactation period). Some descriptions on the messages are in the swagger documentation, but it is not easy to extract those onto the wiki. Maybe this is simply some work that we have to do manually.

[ahokkonen]

btw, there are one tool we can try to migrate JSON documentation into easy readable markdown form:

https://github.com/adobe/jsonschema2md

Haven't tried this yet, but I'll give it a chance.

[ahokkonen]

btw, there are one tool we can try to migrate JSON documentation into easy readable markdown form:

https://github.com/adobe/jsonschema2md

Haven't tried this yet, but I'll give it a chance.

seems like this tool is not very useful for our case, so I'm agree with @alamers to start doing this work manually, at least at the beginning. I can help with updating docs if I'll get permissions for wiki.

[cookeac]

I have created a summary in the Wiki at https://github.com/adewg/ICAR/wiki/Resource-entities.

[alamers]

• use of tickets is mentioned on main readme, so that part is done
• added a link to the resources from main readme and added it to pull request removed redoc since it does not work anymore with current spec #123

This pull request closes all open doc issues in this ticket.