fc4-framework

5. The Authoring Workflow « The FC4 Methodology

Please note: the current workflow is temporary. We know it’s highly manual and that that’s not efficient or sustainable. But it’s sufficient for now, for the current pilot/prototyping phase of this methodology.


Once a basic YAML file has been created with some initial contents, the basic authoring workflow is:

  1. Create a new git branch in your local instance of the diagram repository
  2. In your text editor: either create a new diagram source file or open an existing diagram source file
  3. In a terminal, in your fc4 working dir, run cd tool && ./wcb
    1. This starts the tool in a mode wherein it will watch your clipboard for diagram source YAML and process (clean up) that YAML when it sees that it’s been changed.
  4. In your text editor, add/revise elements and relationships, then select-all and cut the diagram source from your editor into your system clipboard.
    1. This will cause fc4-tool to process the contents of your clipboard.
  5. Switch to Structurizr Express (SE) » paste the source into the YAML textarea » press tab to blur the textarea
    1. SE will either render the diagram, or display a red error indicator in its toolbar
    2. If SE shows its red error indicator, click the indicator button to bring up a dialog listing the errors
  6. Use SE to arrange the elements and edges as desired
  7. Cut the diagram source from the SE YAML textarea into your system clipboard.
    1. This will cause fc4-tool to process the contents of your clipboard.
  8. Paste the diagram source back into the SE YAML textarea so as to re-render the diagram, now that the elements have been “snapped” to a virtual grid.
  9. Continue to cut and past the diagram source between your text editor and SE, using SE to preview and adjust the rendered diagram, while fc4-tool cleans up the diagram as you work.
  10. When you’re ready to wrap up:
    1. Paste the diagram source into your text editor and save the YAML file.
    2. Paste the diagram source into SE, hit tab to re-render the diagram, then click the Export to PNG button in the toolbar.
    3. The rendered diagram will open in a new browser tab.
    4. Save the rendered diagram to a PNG file next to the YAML file and with the same name as the YAML file, except for the filename extension of course.
  11. Use your git UI of choice to commit your changes.
  12. Push your local changes to the origin repository regularly.
  13. When you’re ready to submit your changes for review, open a Merge Request or Pull Request to get your changes reviewed and then merged into master.

That’s pretty much it, right now.

Soon we’ll start looking into less manual, more automated workflows for authoring and rendering the diagrams.


Please continue to Publishing or go back to the top page.