CMS-WS Meeting Minutes 2019-01-21
Table of Contents
Date/Time
Attendees
Name | Organisation |
|---|---|
@Leo Papadopoulos | Cloud9 |
@Vitor Espindola | Byne |
@Oliver Kemmis | comitFS & Globility Ltd. |
Outstanding Action Items
Agenda
Time | Item | Who | Notes from the Meeting |
|---|---|---|---|
5 min | Convene & roll call |
| Noted that it is a US bank holiday today. Agreed to put out notes and ask the team if they want to have an extra meeting this month. |
10 min | Review action items from previous meetings |
| @Leo Papadopoulos cleaned up repo. Delivered draft spec to be cleaned up some more and delivered this week. Comments by @Vitor Espindola to also be merged in my end of this week. |
Status, Questions, and Next steps | @Leo Papadopoulos Spoke about merged cleaned up repo. @Leo Papadopoulos Spoke about a goal of putting out a draft specification by end of March. Then a roadmap for the rest of the year. @Vitor Espindola was confused as to whether the comments should be again the YAML or the JSON file. The answer is YAML. @Leo Papadopoulos to clarify this in the readme for the project. @Leo Papadopoulos clarified questions from @Vitor Espindola that there should be one specification that covers all call types. (Dialtone, DID, Shoutdown, Ringdown, Intercom, etc) @Oliver Kemmis agree to contact schema.org one more time to see if there is a better way to auto-generate documentation for the JSON spec for call metdata. @Vitor Espindola also agreed to think about any suggestions he have have on this topic. The group agreed that after this week when @Leo Papadopoulos merges in Vitors PR and performs final clean up then we will begin working on incorporating ideas form other team members to work towards a specification.
| ||
5 min | AOB & adjourn |
|
|
Decisions Made
See above.
Action Items
Also see above
@Leo Papadopoulos I've searched and tried some tools to auto-generate documentation from json-schema. Most of the tools are created for generating API documentation which I think does not suit our project. Below I list the results of the tools that I've evaluated and the results:
* Adobe jsonschema2md (https://github.com/adobe/jsonschema2md): A good tool supported by Adobe. You can check the results here: https://gist.github.com/vitorespindola/2b42d2b4831d796ef6a279bbef017b9a. It generates Markdown file, and from Markdown we can generate a lot of other outputs with tools like mkdocs.
* JSchemer(https://github.com/dwhieb/jschemer): Looks promising, just need to make some changes on our schema to work. You can check the results here: https://jsfiddle.net/5spy27k4/embedded/result/
* DOCA from Cloudfare(https://github.com/cloudflare/json-schema-tools): A set of tools for building API documentations and depends on JSON Hyperschema. The project provides a set of tools to work with JSON Schema, but this requires that we build our own tool to generate the documentation.
* Wetzel(https://github.com/AnalyticalGraphicsInc/wetzel): JSON Schema is not fully supported yet, also I cannot make it work. Since I'm not a Node.js expert I think it's a problem with my environment. Maybe we should give another try.
We can also try to document the project in a more descriptive way like documenting it on Markdown or some other format and make references to the JSON Schema:
* XML2RFC - A XML format to describe documentation in IETF RFC format. JSON Schema project uses this to generate it's documentation and also the RFC format output(http://json-schema.org/latest/json-schema-core.html) as you can see in the repository: https://github.com/json-schema-org/json-schema-spec. I like this option since we are all confortable reading IETF RFC files.
* Sphinx(http://sphinx-doc.org/) - Sphinx is a great tool for documentation and there are some plugins to add references to JSON Schema.
* Markdown + mkdocs(https://www.mkdocs.org/) - Mkdocs allow us to generate documents from Markdown to a lot of formats(Including HTML, Latex, ePub).