[DOC] rework README and documentation site

[tbouffard]

Note: based on decisions shared by @aibcmars, @csouchet and @tbouffard

Current status

The documentation is splitted into the README, the developers documentation (in the docs folder) and the html/asciidoctor/site documentation. The perimeter of the developers documentation is clear but the difference between the README and the html documentation is not. As a result, we have information duplication between the 2 documentations and some information are not synchronized. In addition, we also have duplications with the README of the examples repository.

We want to make the situation clearer for our users and to reduce the maintenance.

Changes we want to apply

Clarify the purpose of each documentation

The README file

• project introduction
• basic usage
• links to examples and developers or html documentation for more details

The HTML documentation

• high level information, contextual content
• BPMN support details
• Architecture

Tasks

• [x] create a documentation.md file in the docs folder to explain this clearly. This file could also document how to generate the html documentation currently explain elsewhere
• README
  • [x] list the lib features (for bpmn support, link to html doc) and the browser support (to be documented in a common section)
  • [x] explain how to use the lib for an integration (quick-start). Simplify it for something like we have in the quick-start of the example repository
  • [x] highlight links to the example repository (depends on https://github.com/process-analytics/bpmn-visualization-examples/issues/87):
  • simplification of demo/examples live environment: a single link to the example home live environment
  • 'demo' badge update: link to the example home live environment
  • no more ref to how to find BPMN file to be used locally
• HTML Documentation
  • [x] remove duplicate content
  • mini intro, no feature nor browser support list
  • no more usage details: add link to README and/or examples if needed
  • [x] architecture BPMN model: remove information about how to update it, this is a developer information, so put it in the developer BPMN support documentation

[csouchet]

An example of Contributing guide/doc: https://p5js.org/contributor-docs/#/

[tbouffard]

Closing as all tasks are completed.