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:
- Create a
doc branch
based onmaster(main)
branch - The branch with the same content like
master(main)
will be created - User(s) can update the documentation (.md files)
- Register (if not already done) and login to our application
- Import the Git project with docs
- Change the working branch to the created
doc branch
- Start a new doc in our app
- Create manually the structure (ToC) of the new document
- Save your new doc in our application, publish to create a versioned copy and push to Git repo
- Our application will push to your Git project new updated DOCX and PDF documents
- Issue a Pull/Merge request to start approval/review process and add all optional/required approvers
- Pull/Merge request will be issued for merging
doc branch
intomaster(main)
- Approvers (optional and required) will review the content
- (Optional) Approvers comment the content if something to correct in the Pull/Merge request
- Users update the content as per feedback from approvers and resolve all comments (sometimes conducting the discussion) in the Pull/Merge request
- Pull the new content, save your new doc in our application, publish to create a versioned copy and push to Git repo
- Our application will push to your Git project new updated DOCX and PDF documents
- Approvers confirm they are happy with the content by approving Pull/Merge request
- User will merge Pull/Merge request (if not set to auto-complete)
- The
doc branch
is merged intomaster(main)
and your new content is now official
NOTE: Keep in your
master(main)
only approved content