User Story
As a PRACTICAL ™ Product Manager, I don’t want to be bogged down with technical complexity. For example, the use of our current Jekyll documentation template leads to technical concerns such as Jekyll Frontmatter, and the sidebar.yml file.
Jekyll Frontmatter
In Process
If we are to use this Jekyll template for our HTML generation, then the frontmatter should be limited to simple concepts that are easy for the Product Manager to understand, such as:
- A title for this page
- A summary of the requirement this page represents
- Some keywords for this page
Anything else is noise which should be factored out by the engineers of the PRACTICAL ™ Documentation System.
Sidebar Yaml File
Not Started
Another issue is the inclusion of the sidebar.yml file. Every time you add a page, you have to go update the sidebar.yml file to get that page to show up in the navigation.
While this provides a nice way to control the navigation and control when a page becomes public, I’m sure there’s got to be a less technical means of controlling these things.
For example, we could automatically generate the sidebar data based on the list of files in the folder, and use some frontmatter for controll such as:
- “draft: true” to keep a page from being shown in the sidebar until we’re ready to publish it.
- “parent: path_to_parent.html” to set up the nesting of pages.
Required Includes
Completed
Our current Jekyll documentation template requires an include at the bottom of the markdown for each page. The required entry looks like this:
[comment]: # (Don't edit below this line please)
{ % include links.html % }
There’s got to be a way for the Engineers to factor this out!