Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.Sign up
Nice to see our first contribution to the documentation from outside ECA personnel :)
Few notes, though.
The documentation should be written in a language which is neutral. It should not have any mention of product names, companies, or proprietary tools, protocols, services or products.
All information in the documentation should be written so that it can be used to implement the service or interface. If there are mentions of software or code that needs to be open and licensed with ECA compatible license.
The primary readers of this documentation are service providers who are implementing their own Bazaar. The LMS and CMS implementers are secondary, but are also using this documentation.
Reference implementation in the form of source code would be preferred to prove that the interface documentation in this repository is possible to implement in a production system. ECA has defined that it would be best if everything in the documentation is backed by open and free reference implementation.
There are more comments inline in the commit. There are a lot of them mainly because there are no examples and reference implementation of the interface. The specification must be pretty precise so that different services know how to implement it the same way.
We've been using https://www.websequencediagrams.com/ service to create sequence diagrams before. It renders the diagram as PNG from a text representation. The text can be committed to the repository and it is understandable as is. This way we are not bound to any proprietary tool to generate diagrams. Also it's fun to create those :)