[DX] Improving docs for Workflow #10747
Comments
|
For 1: I think this makes sense. We strip down the theoretical part to a small paragraph and move the rest to a new chapter. This new chapter then also could better explain the differences between workflows and state machines (thus solving 2.). For 3: After having done 1. we could probably also add a dump example and link to the related article there. For 4: Here I am not sure either, but we should think about it. |
|
Hi I have now been spending my first couple of hours with this interesting component at #SymfonyConHackDay2018. Here are my first thoughts about it: For 2: I totally agree. I don't think all developers are familiar enough with the topic that they could tell the difference between a workflow and a state machine. The documentation should give more help on making the decision which one to use and the differences between the types. For 4: Agree. It took me a while to realize what the marking_store arguments does. We could say that "The argument is the property path in the object where the marking store tries to set the current place" The documentation on Using Events is pretty clear. However it is missing everything about TransitionBlockers which are essential to give users feedback about why a certain transition cannot be applied. Especially when there is a custom Guard Event blocking the transition. |
This PR was squashed before being merged into the 3.4 branch (closes #11437). Discussion ---------- Reorganized the Workflow docs This fixes most of #10747. Main changes: * The main workflow article + the state machines article have been merged into a theoretical introductory article about workflows and state machines. * The "usage" article has been deleted and its contents moved to the main workflow article. ------ Missing things: * We need to solve the (4) idea from #10747, which I don't understand. Thanks! Commits ------- 486b978 Reorganized the Workflow docs
|
@jzawadzki @tjantika @xabbuh is this issue still pending ? |
|
Let's close this as fixed, because the last remaining issues about "blocking transitions" should be fixed because it's already explained in the docs. Thank you all! |
Hi,
I would like to mark couple of ideas to improve Workflow component documentation
Main page: https://symfony.com/doc/current/workflow.html
This page is currently only showing information about what workflow is and not what it is in Symfony - I think we could move here information from https://symfony.com/doc/current/workflow/usage.html (beside events part probably, which could go to separate page)
I think we could better show on main page difference between workflow and state machine - when you would like to use one or other. Maybe an additional example of state machine beside the link to "Workflow as state machine"?
Better way of showing
php bin/console workflow:dump- currently to see this extremely helpful command, I need to go to the bottom of "How to dump workflows" page - I think we could add some information on that right after the configuration examples?Currently when you would not set up
marking_store(which you would not, if you are copying yaml example from https://symfony.com/doc/current/workflow/state-machines.html like I did) you are getting following exception:An exception has been thrown during the rendering of a template ("Neither the property "marking" nor one of the methods "getMarking()", "marking()", "isMarking()", "hasMarking()", "__get()" exist and have public access in class "App\Entity\Task".").That is because
markingis the default field for marking store, but that's only noted in small tip on https://symfony.com/doc/current/workflow/usage.html.Not sure if this is a documentation issue or we can improve DX in a code itself to show better exception message?
Let me know what you think - I would be more than happy to start WIP pull request for above changes.
#SymfonyConHackDay2018
The text was updated successfully, but these errors were encountered: