tag-contributor-strategy
tag-contributor-strategy copied to clipboard
cncf
Render the reviewing.md template on the website
In our governance meeting today, Josh brought up that some people had trouble when we linked them to a github markdown file and said "use our templates!". Since the transition to git may be a sticking point for people even reading what we are recommending, once a template has been transitioned from inline html comments in the markdown file to the HowTo format, let's render the template directly on the website.
We can then provide a link to the rendered template on the site, and from the rendered page, provide a link to the original source in git so that anyone inclined can use git to copy the template.
Reviewing.md is the first template that's been migrated and it's ready to have its template up on the site.
@jberkus I don't have enough info to know how to implement this:
- Did you want the rendered template, or a code formatted display of the markdown (like what you would see if you clicked raw in the github view of the template)?
- Should we include the normal header/footer for the website?
I'm not quite sure what the format should be to make it easy to copy and use but rendering it would make all of the links break.
I'm trying to remember this conversation and what it was we were actually trying to do.
I'm tempted to close it and if we remember, we can reopen with more context. 😀 Deal?
I remember this conversation. Our concern was that GitHub can be a barrier for some people who aren't as involved in day to day work on code within open source projects. We talked about how putting the templates onto the website might make them more accessible to people who don't live in GitHub where they can read our templates and get ideas for their own governance. Also, some projects outside of the CNCF ecosystem tend to keep governance docs on the website, instead of in GH. There was also a discussion about some other groups who were getting together to talk about open source governance (maybe the IEEE group), and by having nicely formatted web pages, it might be easier for other efforts to consume our templates.
From my perspective, I think we don't worry about preserving the markdown so that people can easily copy them into a repo (our templates directory is better for that), but instead put the focus on making them easy to read and consume via the web.
Does this ring any bells?
How and where do we want to display the rendered template on the site? Will we link to them from the How To?
I'm concerned that if we render the markdown for the template on the website, then people will try to copy/paste that (which doesn't work well) instead of using the template file. So we'll need to make sure that it's still clear where to get the template from.
+1 to making it really clear about where to get the actual markdown template. I don't have any strong opinions about where we put them on the site.
If anyone has suggestions, drop them here. Otherwise I'll try mocking something up when I get a chance this week and bring back a screenshot or two that we can think about.
Sounds like we have two copies, one in actual project-templates, and a 2nd copy formatted for the website in /content/?
I'm really hoping that we don't do that actually since they will inevitably get out of date. But that's partly why I'm asking what we want to show on the site.