New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initial Edustore version #3

Open
wants to merge 2 commits into
base: master
from

Conversation

Projects
None yet
2 participants
@pkarppi
Contributor

pkarppi commented Sep 1, 2015

Initial Edustore version.

@derega

This comment has been minimized.

Show comment
Hide comment
@derega

derega Sep 9, 2015

Member

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

Member

derega commented Sep 9, 2015

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

Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Use case:
Person wants to view selected material/resource.
API workflow:

This comment has been minimized.

@derega

derega Sep 9, 2015

Member

Same comments apply here as above.

@derega

derega Sep 9, 2015

Member

Same comments apply here as above.

Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
Show outdated Hide outdated bazaar/interface.rst
@derega

This comment has been minimized.

Show comment
Hide comment
@derega

derega Sep 9, 2015

Member

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

Member

derega commented Sep 9, 2015

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment