filiphr
commented
3 years ago Thanks for the feedback @jbeck111. Would you be interested in creating a PR with the updated text for the Getting Started? The file is https://github.com/flowable/flowable-engine/blob/master/docs/docusaurus/docs/bpmn/ch02-GettingStarted.md.
Describe the bug This affects: https://flowable.com/open-source/docs/bpmn/ch02-GettingStarted/#starting-a-process-instance https://github.com/flowable/flowable-engine/blob/master/docs/userguide/src/en/bpmn/ch02-GettingStarted.adoc
The Getting Started guide is informative and perfectly clear until line 276, when suddenly the new user is abandoned to their own instincts and prior knowledge of Java.
Before that point, the instructions include steps, filenames and locations, and complete code to go in the file. Examples:
That was great; nice and clear.
But after that point, it changes to general advice, and assumes you know where to implement it. Examples:
After that sentence a snippet of code is provided, but the user is not told where to put it.
Happily I tried putting it in the main entry point method, and it was OK. (This was the instruction that should have been provided to the user instead of abandoning them to flail about helplessly.)
The same is repeated a few times after that.
But enough description of the bug.
How to Fix Simply follow these instructions.
Locate this text "Using the RepositoryService, a new Deployment is created by passing the location of the XML file and calling the deploy() method to actually execute it" Insert this sentence after it, before the code snippet: "Add the following code to the end of your main method in HolidayRequest.java"
Locate this text "This is done by creating a new ProcessDefinitionQuery object through the RepositoryService." Insert this sentence after it, before the code snippet: "Add the following code to the end of your main method in HolidayRequest.java"
Locate this text "In this example, we’ll keep it simple and use the java.util.Scanner class to simply input some data on the command line". Insert this sentence after it, before the code snippet: "Add the following code to the end of your main method in HolidayRequest.java"
Locate this text "This key matches the id attribute that is set in the BPMN 2.0 XML file, in this case holidayRequest." Put the subsequent xml snippet here, pulling it further away from the java code that follows it. Otherwise it looks like part of the java code. Now comes your next sentence: "(NOTE: there are many ways you’ll learn later on to start a process instance, beyond using a key)" Leave a gap. Insert this sentence before the java code snippet: "Add the following code to the end of your main method in HolidayRequest.java"
Now tell the user to run the code again, and mention that they will be prompted for process variables from the command line.
I had named my main java file HolidayRequest.java and this was not specified in the Getting Started guide. It makes sense to call it that, but you can't assume people will do it, and these instructions now depend on it. So make the filename clear:
Locate this text back near the start: "Create a new Java class and add a regular Java main method:" Change it to "Create a new Java class in a file 'HolidayRequest.java' and add a regular Java main method"
Locate this text: "To do this, add the candidateGroups attribute to the first task" User has been in java code and should be re-oriented, so change it to "To do this, back in the xml file add the candidateGroups attribute to the first task
Locate this text: "To get the actual task list, we create a TaskQuery through the TaskService and we configure the query to only return the tasks for the 'managers' group" Put this after the above: "Back in java code, add the following to your main method"
That's all.