search

educloudalliance / eca-docs

Educloud Alliance Technical Documentation. You should start reading here :)
http://docs.educloudalliance.org/
0 stars 5 forks source link

Initial Edustore version #3

Open pkarppi opened 9 years ago

pkarppi commented 9 years ago

Initial Edustore version.

derega commented 9 years ago

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 :)

derega commented 9 years ago

Whoops! Those inline comments came here in the wrong order. Sorry :)