WIP/working list of Docs for clarity updates

Community Contributions & Discussions
1

This is a working list of docs to get PRs with “clarity updates”.
basically doc pages that usually already have the content but it could use some additional simplification or more commonly, additional prominence on the page.
Feel free to post additional requests.

  1. Call Activity: Combination with Input and Output variables: Clarification of Docs: Call Activity: Combination with Input/Output parameters

  2. Getting and Setting Process Variables (especially with scripting)

  3. Candidate User/Groups vs User/Group Constructions: Candidate User / Groups vs Potential User/Groups constructs? - User Task Assignment

  4. Curl Deployment examples: forms, files, etc

  5. Arrays/Collections as Process Variables or Task variables

  6. Additional common Timer usage examples (date, duration, cycle)

  7. Updates to docs around Embedded Forms formKey in Modeler/XML. embedded:deployment:form key

  8. camForm usage variables/info such as getting Deployment ID from camForm object.

  9. Additional SPIN usage examples for Scripting, and common use cases

  10. Loading files from a deployment through rest API within form.

  11. Pool/Lane coverage explanation. (no section currently in docs Ref > BPMN2>?)

  12. http-connector configuration in Modeler + Use case scenarios for GET and POST (HIGH PRIORITY - Lots of Forum questions ask about the usage)

  13. broken links at bottom of page: https://docs.camunda.org/manual/7.4/webapps/tasklist/tasklist-plugins/ see: https://github.com/camunda/camunda-docs-manual/pull/90

  14. EL/Expression language common use cases and examples. Concat, etc

  15. cleanup of : https://docs.camunda.org/manual/7.5/user-guide/process-engine/scripting/#variables-available-during-script-execution

  16. Additional scripting examples when using execution variable and accessing engine services

  17. Business Key creation and use cases: only being able to create at process start, etc. (support: Business Key)

  18. JavaScript scripting: use of Nashorn and the “extras” that Nashorn provides (support: https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/nashorn/).

  19. Additional Scripting Examples of usage of DelegateExecution and chaining with ProcessEngineServices

  20. execution javadocs usage (based on convo in: Using JS SDK helpers in Task Scripting?)

  21. Broken link on page: https://docs.camunda.org/manual/7.5/reference/bpmn20/events/timer-events/#time-cycle. The CronTrigger Tutorial link is broken.

  22. Boundary events (incl. Timer Boundary Events) cannot be updated during Execution Listener Start Event: User task timer boundary event based on expression set in user task listener. The boundary events are evaluated during activity initialization, which occurs before Execution Start.

  23. engine doesn’t support receive tasks in combination with an event-based gateway. as per: Calling several Receive Tasks

2

Hi @StephenOTT,

Thanks for undertaking the effort of improving the docs. I’m looking forward to any pull requests :slight_smile:

One consideration: In my opinion, good documentation should enable any reader (unexperienced as well as expert) to apply the described concepts in practice. The challenge is to find the right level of detail that actually helps people but also keeps the focus on Camunda concepts/APIs.

In that sense, for some of the points above that are not directly related to understanding Camunda concepts but rather to understanding a technology that Camunda integrates with (e.g. in your list: EL, Curl, Nashorn), I propose to link to external resources. External resources could be our own examples (https://github.com/camunda/camunda-bpm-examples), as well as blog posts or reference documents. What do you think?

Edit: Blogposts could even go on the blog.camunda.org blog. For example, a focused blogpost on EL syntactic sugar in the context of process execution could certainly go there (see repo https://github.com/camunda/blog.camunda.org).

Cheers,
Thorben

3

100% agree and that was the plan. The goal was not to add content that was duplicated in other places. But to add the proper context, structure and/links to the context that allows people to “connect the dots”.

In some cases (let’s use curl as the example), it is not that lots of examples are needed, just a single simple code snippet provides all of the context needed for someone to fully understand the concept and how to use on a basic level.

1 Like
4

:thumbsup:
What are your thoughts on linking to blog posts from within docs?

5

For any non-Camunda blog post, there is of course always the risk of the blog becomes unavailable or changes content-wise. I think that linking to blogs fine is for anything that is not a Camunda core concept but a “Further/Related Reading” topic (e.g. an EL cheat sheet). So the docs should still make sense without the blog contents. In addition, such links should be well selected, i.e. I’d prefer quality over quantity.

We could also consider having boxes (like here: https://docs.camunda.org/manual/latest/user-guide/process-engine/process-engine-concepts/#process-definitions) of such external resource links at the end of documentation sections.

6

Additional:

  • Usage Pattern for Updating Timers using the Rest API

@camunda is there a change on the length of time a post can be edited before it becomes “locked”?

7