Generate MD Books locally for developers of training
What problem(s) will it solve?
What problem do we solve?
As a developer of training, I would like to be able to ensure that the content is generated as planned. Additionally, being able to generate mdbooks locally may help to identify issues that are not readily apparent when looking at the raw md.
Who is the intended user(s)?
Developers of training and other SME may build MDBooks locally to guarantee quality and uniformity of training products. Additionally, developers of training may use this functionality to try out and evaluate non-routine / novel uses of MD in training materials.
Lay out the expected user experience
What is the single user experience workflow this problem addresses?
The developers of training should be able to develop mdbooks independently of merge requests in order to be able to experiment and troubleshoot with fidelity to the actual generated product - without imposing a merge request on the master branch.
Proposal
How are we going to solve the problem? Create a work flow or reproducible environment that allows quick generation of mdbooks from local branches.
Further details
Include use cases, benefits, goals, or any other details that will help us understand the problem better.
Simple documented steps may be more desirable than requiring an image or container - unless it can be spun up as easily as theDocker instances with VSCode.
Permissions and Security
What permissions are required to perform the described actions?
Permissions are consistent with public read access. Anyone who can fork, should be able to build the mdbooks locally.
Documentation
See the Feature Change Documentation Workflow Gitlab Feature Change Workflow
The steps to create the environment and generate mdbooks locally should be listed in a readily identifiable location.
Update User Documentation
The steps to create the environment and generate mdbooks locally should be listed in a readily identifiable location. This should not affect other user documentation.
Update Developer Documentation
This will be included with other developer of training documentation.
-Is there any other documentation affected? None that this author is aware of.
Availability & Testing
See the test engineering planning process and reach out to your counterpart Software Engineer in Test for assistance: Gitlab Test Planning
This section needs to be retained and filled in during the workflow planning breakdown phase of this feature proposal, if not earlier.
What risks does this change pose to our availability?
Being able to generate mdbooks locally will not affect availability. Allowing developers of training to generate mdbooks locally may improve quality. Depending on the requirements - cross-OS testing may be required.
What does success look like, and how can we measure that?
Success is a product that allows developers of training to independently generate mdbooks from local branches. The acceptance criteria - a developer of training is able to use the provided solution to generate mdbooks from a local branch.