[Content] Add a Documentation Guidelines page

[briandominick]

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:

• A reference to an upstream style guide, such as Google's or Microsoft's
• Any known style preference modifications
• A "Terminology" section for CC-specific usage or CC "proprietary" terms and how they're used
• Descriptions of different flavors of Markdown used in different places, and any syntax preferences
• Recommended tech-writing and Markdown resources

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

• [x] I would be interested in implementing this feature.

[TimidRobot]

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).

[TimidRobot]

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)

[TimidRobot]

I suspect the Google Devs style guide is more appropriate

This rings true for me

[briandominick]

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.

[briandominick]

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.