[DOC] clarify contributors and users documentation folders (#904)

Split the documentation into 2 folders to clarify who is targeted by the
various parts of the documentation.

CONTRIBUTING.md

@@ -25,17 +25,17 @@ If you start working on one of the existing [issues](https://github.com/process-
 
 3. Do not commit changes to files that are irrelevant to your feature or bugfix (eg: `.gitignore`).
 
-4. Provide [tests](./docs/development/development.md#tests) and documentation whenever possible.
+4. Provide [tests](./docs/contributors/development.md#tests) and documentation whenever possible.
 
-5. Be sure you have followed the [code style](./docs/development/development.md#code-style) for the project.
+5. Be sure you have followed the [code style](./docs/contributors/development.md#code-style) for the project.
 
 6. Prior opening a Pull Request, ensure the build is fully working by locally running `npm run all` (build, check and
 test everything)
 
-7. Open a [GitHub Pull Request](./docs/development/pull-request.md#open-a-pull-request) with your patches. (**1** pull request = **1** feature or bug)
+7. Open a [GitHub Pull Request](./docs/contributors/pull-request.md#open-a-pull-request) with your patches. (**1** pull request = **1** feature or bug)
    We will review your contribution and respond as quickly as possible. Keep in mind that this is an open source project, and it may take us some time to get back to you. Your patience is very much appreciated.
 
-8. If this is your 1st Pull Request, sign the [Contributor License Agreement](./docs/development/pull-request.md#sign-the-contributor-license-agreement)
+8. If this is your 1st Pull Request, sign the [Contributor License Agreement](./docs/contributors/pull-request.md#sign-the-contributor-license-agreement)
 
 9. Be willing to accept criticism and work on improving your code. 
 
@@ -54,11 +54,11 @@ git checkout -b 25-annotations_to_tasks
 ```
 
 ### IDE configuration
-To know how configurate your development environment, see [IDE configuration](./docs/development/ide-configuration.md).
+To know how configurate your development environment, see [IDE configuration](./docs/contributors/ide-configuration.md).
 
 ### Development
 
-You'll find [here](./docs/development/development.md) the necessary information to build, test, lint your code, and some tips too. 
+You'll find [here](./docs/contributors/development.md) the necessary information to build, test, lint your code, and some tips too. 
 
 ### Commit in your branch
 There is no convention for the commit message in your branch.
@@ -69,11 +69,11 @@ The most important part is the title of the Pull Request, because:
 
 ### Pull Request
 
-After your development finished, you need to open a Pull Request. You'll find [here](./docs/development/pull-request.md) all the necessary information to open it and to keep it updated.
+After your development finished, you need to open a Pull Request. You'll find [here](./docs/contributors/pull-request.md) all the necessary information to open it and to keep it updated.
 
 
 At this point, you're ready to make your changes! Feel free to ask for help. Everyone is a beginner at first 😸
 
 ## Maintainers
 
-See the necessary information for the [Maintainers](./docs/development/maintainers.md)
+See the necessary information for the [Maintainers](./docs/contributors/maintainers.md)

README.md

@@ -1,6 +1,6 @@
 <h1 align="center">BPMN Visualization</h1>
 <div align="center">
-    <p align="center"> <img title="BPMN Visualization" src="docs/images/diagram-example.png"></p>
+    <p align="center"> <img title="BPMN Visualization" src="docs/users/images/diagram-example.png"></p>
     <p align="center"> 
         <a href="https://npmjs.org/package/bpmn-visualization">
           <img alt="npm package" src="https://img.shields.io/npm/v/bpmn-visualization.svg?color=orange"> 
@@ -127,7 +127,7 @@ You can find more detail in our [Contributing guide](CONTRIBUTING.md). Participa
 `bpmn-visualization` is released under the [Apache 2.0](LICENSE) license. \
 Copyright &copy; 2020, Bonitasoft S.A.
 
-Some BPMN icons used by `bpmn-visualization` are derived from existing projects. See the [BPMN Support page](docs/bpmn-support.adoc)
+Some BPMN icons used by `bpmn-visualization` are derived from existing projects. See the [BPMN Support page](docs/users/bpmn-support.adoc)
 for more details:
 - [draw.io](https://github.com/jgraph/drawio) (Apache-2.0)
 - [flaticon](https://www.flaticon.com) ([freepikcompany license](https://www.freepikcompany.com/legal#nav-flaticon))

docs/contributors/README.md

@@ -0,0 +1,22 @@
+# Guidelines for Contributors and Development
+
+General information are available in the [Contributing Guide](../../CONTRIBUTING.md).
+Information about the library internals are available in the [architecture folder](../users/architecture) or in html form in the [documentation site](https://process-analytics.github.io/bpmn-visualization-js/#_architecture_and_development)
+
+Here are some tips to help during development.
+
+## Build and develop
+
+- [how to build & code style](development.md)
+- [IDE configuration](ide-configuration.md)
+
+## Contributing
+- [testing](testing.md)
+- [how to support new BPMN elements](bpmn-support-how-to.md)
+- [how to submit your work](pull-request.md)
+- [mxgraph integration](mxgraph-integration.md)
+- [mxgraph version bump](mxgraph-version-bump.md)
+
+## Misc
+- [documentation guidelines](documentation-guidelines.md)
+- [for the maintainers](maintainers.md)

docs/development/bpmn-support-how-to.md → docs/contributors/bpmn-support-how-to.md

@@ -44,12 +44,12 @@ Refer to existing Pull Requests to have a better view about the work to do, for
 When changing the model, the image representing the model in the documentation needs to be updated as well.
 
 The documentation uses the SVG image produced from draw.io file.
-This file is stored [here](../architecture/images/architecture/internal-model.drawio).
+This file is stored [here](../users/architecture/images/architecture/internal-model.drawio).
 
 To update the model
-- edit [internal-model.drawio](../architecture/images/architecture/internal-model.drawio) with https://app.diagrams.net or with the `diagrams.net` desktop application
+- edit [internal-model.drawio](../users/architecture/images/architecture/internal-model.drawio) with https://app.diagrams.net or with the `diagrams.net` desktop application
 - store the modified file in the repository 
-- don't forget to export it as SVG and store it in [the repository](../architecture/images/architecture/internal-model.svg) as well
+- don't forget to export it as SVG and store it in [the repository](../users/architecture/images/architecture/internal-model.svg) as well
 
 
 ### What to change?

docs/development/development.md → docs/contributors/development.md

@@ -1,8 +1,8 @@
 # Development
 
 **Note**:
-- information about the library internals are available in the [architecture folder](../architecture) or in html form in the [documentation site](https://process-analytics.github.io/bpmn-visualization-js/#_architecture_and_development)
-- additional information related to development can also be found in the [development details page](.//README.md)
+- information about the library internals are available in the [architecture folder](../users/architecture) or in html form in the [documentation site](https://process-analytics.github.io/bpmn-visualization-js/#_architecture_and_development)
+- additional information related to development can also be found in the [contributors guidelines page](./README.md)
 
 ## Requirements
 

docs/development/documentation-guidelines.md → docs/contributors/documentation-guidelines.md

@@ -2,13 +2,13 @@
 Below guidance should serve to write the properly distributed documentation and to avoid any duplications.
 
 Projects documentation consists of:
-- HTML documentation - everything at the root of the docs/ folders and under /docs/architecture
+- HTML documentation - everything under the /docs/users folder, with AsciiDoctor sources
     - High level information
     - Contextual content
     - BPMN support details
     - Architecture overview
 
-- Markdown documentation for Developers / Integrators - all .md files in project root and under /docs/development
+- Markdown documentation for Developers / Integrators - all .md files in project root and under /docs/contributors
     - Development guidance
     - How tos
     - Detailed usage

docs/architecture/development.adoc → docs/users/architecture/development.adoc

@@ -11,5 +11,5 @@ endif::[]
 [TIP]
 ====
 - To know how to build the project, please have a look at the https://github.com/process-analytics/bpmn-visualization-js/blob/master/CONTRIBUTING.md[contributing guide].
-- For any development tips, see the https://github.com/process-analytics/bpmn-visualization-js/blob/master/docs/development[development documentation].
+- For any development tips, see the https://github.com/process-analytics/bpmn-visualization-js/blob/master/docs/contributors[development documentation].
 ====

docs/architecture/mxgraph-integration.adoc → docs/users/architecture/mxgraph-integration.adoc

@@ -5,4 +5,4 @@ https://jgraph.github.io/mxgraph/docs/manual.html#3.1.1[mxGraph model] from the
 
 It also provides the Diagram Navigation support.
 
-For more details, see the https://github.com/process-analytics/bpmn-visualization-js/tree/master/docs/development/mxgraph-integration.md[development documentation].
+For more details, see the https://github.com/process-analytics/bpmn-visualization-js/tree/master/docs/contributors/mxgraph-integration.md[development documentation].

scripts/docs.js

@@ -28,10 +28,9 @@ console.info('Building bpmn-visualization html documentation');
 fse.removeSync(docsOutput);
 
 // build html docs
-Asciidoctor().convert(fs.readFileSync('docs/index.adoc'), {
-  base_dir: 'docs',
-  to_file: `../${docsOutput}/index.html`,
-  // to_file: '../build/docs/index.html',
+Asciidoctor().convert(fs.readFileSync('docs/users/index.adoc'), {
+  base_dir: 'docs/users',
+  to_file: `../../${docsOutput}/index.html`,
   standalone: true,
   mkdirs: true,
   safe: 'unsafe', // needed because we want to generate the html outside of the directory that stores the source files
@@ -40,8 +39,8 @@ Asciidoctor().convert(fs.readFileSync('docs/index.adoc'), {
 // copy images
 fse.ensureDirSync(`${docsOutput}/images`);
 
-fse.copySync('docs/images', `${docsOutput}/images`);
-fse.copySync('docs/architecture/images', `${docsOutput}/images`);
+fse.copySync('docs/users/images', `${docsOutput}/images`);
+fse.copySync('docs/users/architecture/images', `${docsOutput}/images`);
 fse.copySync('src/static/img/favicon.ico', `${docsOutput}/favicon.ico`);
 
 // eslint-disable-next-line no-console