Feedback about documentation and a proposal to reorganize

During my recent workshop with a customer a developer complained about the hard to understand documentation on the Rest API. He hadn't had a training and wasn't working in the core process automation team, his task was to develop a proxy server between frontend and Camunda BPM in Python. So, the Rest API is his main contact point with Camunda BPM.

The REST API docs didn't cover any use case for the API calls and for beginners it is hard to get an overview.

My proposal is now to restructure the documentation in a way to get a User guide and a separate Reference part.

During the last 6 years I've seen the documentation growing and the feature set growing as well. In the beginning CamundaBPM has the prepackaged platform on Tomcat and JBoss as the most important artifacts and the standalone process engine  was not this important. Then Spring Boot arrived and things shifted. But the documentation didn't shift anything, it was only a chapter added to the user guide. And with Camunda Run, the next runtime arrives on the horizon.

My idea of a User guide contains the following main chapters:

1. Runtime alternatives / architecture overview
2. BPMN modeling and deployment
3. Service automation with external tasks
4. Service automation with java delegates
5. User task handling
6. Configuration (Details the developers need to know once the first process is running)
7. Production-ready installation

The User guide should align the learning experience of a beginner and provide sufficient details to the process runinng. Further details can be linked from the Reference part.

Each chapter should handle all runtime alternatives and their specific requirements or restrictions.

The Reference part can get more chapters than today, for all specific configuration options again subdivided by runtimes.

Ideally the documentation aligns somehow with the learning curve that we follow with our trainings and each slide in the developer training is a just a link to the documentation.

If you have any questions about this or need any help or more details, I'm happy to discuss or provide content.

Cheers, Ingo