Open briandominick opened 1 month ago
If we want to add any documentation on the Lektor specific markdown, it can be added to the Write a Blog Post — Creative Commons Open Source page (content/community/write-a-blog-post/contents.lr
).
I also think a terms list is best sourced/maintained as data, such as a YAML object, with HTML output generated at build time, but that overcomplicates the matter when we're better off getting 10-20 key terms defined and into the guide quickly.
Yes, let's start with documenting as content now. In the future we can explore better data structures (ex. Databags | Documentation | Lektor Static Content Management System)
I suspect the Google Devs style guide is more appropriate
This rings true for me
Ah I hadn't seen the "Write a Blog Post" article. We'll cross link the Documentation Guide with that.
Re Lektor-specific Markdown, I was mostly thinking of a link to their markup guidance, but I honestly cannot find any. They introduce a file extensioon .lr
but they barely even mention anywhere that the markup format is Mardown. If I'm missing something, we should definitely point it out to users.
I see in the blogging article you've linked to: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
That seems fine. It links to GH writing guide, but if we can specify any variant flavors for different places, that would probably be helpful.
Problem
The opensource contributors' site lacks guidelines for writing and maintaining tech docs. This leads to inconsistent style and intimidating entry for new contributions.
Description
Starting with a very simple page consisting of:
Alternatives
A nascent style guide is often better handled in a wiki, such as the existing one maintained by CC or just a new one on GitHub. But I think that sets it aside as second-class compared to having a page right alongside the JavaScript, Python, and Translation guides.
I also think a terms list is best sourced/maintained as data, such as a YAML object, with HTML output generated at build time, but that overcomplicates the matter when we're better off getting 10-20 key terms defined and into the guide quickly.
Additional context
I actually don't know what style if any has been applied so far. I suspect the Google Devs style guide is more appropriate, but I'm not terribly familiar with it, and I don't have a strong recommendation. That choice may deserve some discussion in a forum such as Write the Docs or pointing other docs contributors to this Issue, etc.
I also don't know what flavors of Markdown are in use. Obviously GH Markdown for READMEs, but I see the opensource site uses an SSG called Lektor that has
.lr
files that (I think) are a flavor of Markdown? Docs seem unclear.Implementation