Improved documentation (programming model v2)
danielniccoli opened this issue · comments
💡 Feature description
I'd like to suggest that the documentation Create your first durable function in Python is improved. I have some questions that are not answered.
Section Create your local project explains the steps to create your project.
Unfortunately, the guide just jumps to the next section leaving out a critical part of the information. It does not tell you whether you should select any of the templates, or skip this for now.
If you select "Skip for now", no functions (including the starting point function_app.py) are created. And if you select "Azure Durable Functions orchestrator", you get a module DurableFunctionsOrchestrator1 that is never mentioned in the guide (and also no function_app.py, which is later referred to in a confusing way. See below).
At section create your functions it is explained what functions a basic Durable Functions app contains. The title implies that we're creating these functions, but there is no instruction to create anything in that section.
Perhaps it should be clarified that this is purely informational, for example by changing the title to something that does not imply an instruction. Because in its current state it may cause confusion further down. See below.
Continuing where I left off, if you were curious and would try to create them by yourself - because you believe this information is just missing from the guide - you may try to do use the command palette to create the functions manually:
This would create three modules DurableFunctionsOrchestrator1, DurableFunctionsHttpStart1, and Hello1. And pressing F5 would successfully run your first working Durable Functions app.
But again, this will cause confusion further down, because you should not have done that. See below.
In a later section Enable v2 programming model you are confronted with this instruction:
To create a basic Durable Functions app using these 3 function types, replace the contents of function_app.py with the following Python code. […]
This instruction is not precise, because if you followed the guide to this point, there will not be a function_app.py in your project folder. It should be clarified why the file is not there and that you have to create it first.
And if you created the three functions using the the command palette as shown above, you would also not have a function_app.py file, but instead three modules. And you wouldn't know the difference, or when to use what approach.
It should be explained how to get this working with Azurite emulator.
It should be explained the difference between the function_app.py and the modules approach, and when to use what approach.