Some minor issues with documentation

#1

Hi,

I’ve been stepping through the documentation (https://www.flowable.org/docs/userguide/) trying to get my head around flowable, and have collated a small list of minor points I thought might be worth sharing.

  • Section 5.7.4, first use of “cURL”. This didn’t work for me: curl http://localhost:8080/tasks?assignee=kermit. I was always getting an empty list of tasks back. I had to update the workflow XML (defined in section 5.7.2) and add assignee="kermit" into the XML, i.e.: <userTask id="theTask" name="my task" assignee="kermit" />. Not sure if that’s required or if I did something wrong. If there’s no assignee in the workflow definition, does that mean that ANY assignee would get it? (e.g. Kermit in this case.)

  • Section 5.7.6: The Actuator endpoints didn’t initially work for me following the instructions. I had to add a dependency on “flowable-spring-boot-starter-actuator”. Might be worth reiterating this at this point in the docs.

  • Just before section 7.3. it says this: “[[10minutetutorial]]”. Minor copy/paste error maybe?

  • Section 7.3.1’s first sentence says “This tutorial assumes that you have the Flowable demo setup running”. That hyperlink goes to https://www.flowable.org/docs/userguide/index.html#demo.setup.one.minute.version, but that anchor (demo.setup.one.minute.version) doesn’t seem to be found as the link takes you simply to the very top of the docs.

  • Section 9.2 has small typo: “By default, the build-in form engines, sees the properties” (should be “built-in”).

Thanks!

Yoni.

1 Like
#2

Thanks for pointing those typos out. If you have some spare time and would like to contribute to improve the documentation, it would be great. Please see How to contribute.

It’s really easy, and even minor changes to the documentation like these ones help a lot.

#3

Thanks @inakihn. I’ve now done this: https://github.com/flowable/flowable-engine/pull/1404

This covers bullet points 2, 3 and 5 above. The first one I didn’t do anything about as I’m still not clear on what exactly the problem is: is the example XML wrong: should it explicitly add “kermit” as an assignee? And for the second-last one (with the broken link) I wasn’t sure where exactly that should be pointing to. Happy to submit another PR (or add to the existing one) if you want to give me a bit of guidance on these two.

Cheers.

#4

Good morning,

For point 1, I think that modifying the xml of the process would be ok, and saying that the assignee is kermit, as the rest endpoint of tasks created in that tutorial expects an assignee. This userTask is later changed when jpa is added anyway, so I think that makes sense in my opinion.

The last part is a bit more complicated to fix. As far as I understand that 10 minute tutorial, it is showing the analogy between the UI apps and running the engine with java code. I think that just saying

7.3.1. Prerequisites
This tutorial assumes that you have the Flowable demo setup running

And pointing to a different place is not clear. Maybe that part should be expanded and providing a more guided approach of two parts:

  1. Get the UI apps quickly running (Step 15.1 of the docs)
  2. Quick project setup (Step 2.3.1 of the docs)

With some explanation about what the user has at that point: UI apps and a java main class connecting to the same database.

This part of the tutorial and fitting all tutorials together is something that potentially could be improved (me as a newcomer found it difficult to fully understand which is the tutorial to follow)

#5

Thanks again @inakihn.

For the first point, would you like me to create a PR with the XML updated to have Kermit as the assignee? Or do you prefer someone with more involvement to look at that, in case it impacts other areas?

For the second point, I agree that the tutorial is a bit unclear in some ways for a newcomer. Or, maybe it’s not that it’s unclear: maybe it’s more that it could do with fleshing out and having a bit more information and detail. Certainly that’s been my experience. Some of the fundamental questions I have as part of assessing Flowable for an upcoming project, I’m still not clear on (e.g. see Embed workflow modeler in custom spring boot app). So I’ll definitely leave this point to the more experienced folks to implement if/when time allows.

#6

I think that the first one would be great to have the PR, that way it can be reviewed if that change makes sense (as we are a bit in doubt about it).

The second one is fine to leave for now. Hopefully there’s a way of rethinking how documentation looks like and have a bit of rewriting later down the line.

Thanks a lot for the support to the project @yonigibbs

#7

Thanks @inakihn. PR created: https://github.com/flowable/flowable-engine/pull/1407

1 Like