In this section we will explain how to organize Git branches and approval workflow for docs-as-code. The workflow is outlined in the following PlantUML diagram:

Git branches and approval workflow

  1. Create a doc branch based on master(main) branch
  2. The branch with the same content like master(main) will be created
  3. User(s) can update the documentation (.md files)
  4. Register (if not already done) and login to our application
  5. Import the Git project with docs
  6. Change the working branch to the created doc branch
  7. Start a new doc in our app
  8. Create manually the structure (ToC) of the new document
  9. Save your new doc in our application, publish to create a versioned copy and push to Git repo
  10. Our application will push to your Git project new updated DOCX and PDF documents
  11. Issue a Pull/Merge request to start approval/review process and add all optional/required approvers
  12. Pull/Merge request will be issued for merging doc branch into master(main)
  13. Approvers (optional and required) will review the content
  14. (Optional) Approvers comment the content if something to correct in the Pull/Merge request
  15. Users update the content as per feedback from approvers and resolve all comments (sometimes conducting the discussion) in the Pull/Merge request
  16. Pull the new content, save your new doc in our application, publish to create a versioned copy and push to Git repo
  17. Our application will push to your Git project new updated DOCX and PDF documents
  18. Approvers confirm they are happy with the content by approving Pull/Merge request
  19. User will merge Pull/Merge request (if not set to auto-complete)
  20. The doc branch is merged into master(main) and your new content is now official

NOTE: Keep in your master(main) only approved content