This is a crosspost from VanessaSaurus, dinosaurs, programming, and parsnips. See the original post here.
As software engineers we often have to make choices between ideal states. For example, modular development can better assign responsibility, and make development more scoped and thus easier to do. But what are the drawbacks? It could be that choosing a modular approach means that it’s harder to bring things together – things such as documentation, or in some cases, even community. But really I’m thinking about the first, because recently I’ve been crafting a plan to better contribute to the Open Containers Specifications. We’ve assembled a group of talented container enthusiasts, and while we are discussing many interesting ideas, during our discussion it keeps dawning on me that it’s really hard to keep track of things. What do I mean? Well, I keep hearing the same story:
Is that part of the spec? Where does it say that?
The issue is that each single specification is stored in multiple markdown files, and you have to jump between files and even repositories to find what you are looking for. This might be okay if you know exactly where to look and have a strong understanding of the belonging of files (e.g., knowing if a linked markdown is part of the spec or just a reference) but for a new contributor, it’s akin to being lost in the markdown wilderness.
RFC Jekyll
Early in our discussions, @reidpr had a fantastic idea.
I’d love consolidation of the standard into a single coherent document, e.g. RFC style.
I quickly opened an issue, and by chance the topic of being able to share spec content was brought up at the next OCI meeting. I brought up the idea and it wasn’t rejected, so I got to work! This is thus the creation of the rfc-jekyll template. When you arrive at the root, you can choose to view a specification:
And then browsing to the specification shows content in the center, a left side navigation with other files that are defined for the spec, and the right side is a dynamically generated navigation.
The content from the many different specs and files are retrieved across files and GitHub repositories for a holistic, cohesive experience. I find this much easier to navigate than the spec markdown files on their own.
Design
I wanted to emulate the style of a modern RFC memo, but rendered totally dynamically. I also wanted to add some nice features, like being able to click to quickly open a link to edit the document, or open an issue. For the use case of Open Containers, I wanted to render content not only from the repository that served the template, but from multiple repositories across GitHub! For the design that I am prototyping:
- You can combine many different resources across multiple repos to look like one holistic documentation base
- Content is retrieved dynamically directly from the specs and you don't need to rebuild.
- Every section of a spec page has a permalink, and the page has a direct link to edit on GitHub or open an issue.
- Adding new pages comes down to adding metadata for the pages you want.
I won’t go into details of the template, because if you are interested you can read about it here and see the preview here.
Questions for you!
Primarily I’m interested in feedback from the community for the following questions:
- Would it be useful to still render content from local files?
- What kind of supplementary pages would be useful to go alongside specs (working groups, ideas, images?)
- What other features would be useful to have?
And of course please report any issues or bugs!. I made this is evenings over a few days, and I consider it early in development.
Summary
TLDR: This template might be useful to you if you find yourself in similar circumstances of having scattered markdown files across repositories that you want to make more cohesive. It might be useful if you want RFC style documentation for Jekyll, which I didn’t see anyone has created yet. And that’s all I got! I hope that you take a look and can give feedback to make it better. I’ve made a GitHub discussion if you want a more formal discussion board other than issues.