Suggestion: Contributor style guide

[michaeltlombardi]

For people contributing to the documentation, it would be useful to have a reference document or cheat sheet to understand the style guidelines for this project - what gets backticked vs bolded, how should titles be written, etc.

In addition to documenting the practices, there are two extremely useful tools that can help enforce (many) of them:

• markdownlint is useful for linting the markup syntax of the documents.
• Vale is useful for linting the prose of the documents.

Together, they enable you to enforce particular style guidelines and consistency across documentation. They both have integrations with VS Code, enabling author-time feedback, and can support CI validation as well.

Note
I'm a technical writer by trade and I'd be happy to work with you on implementing either of these and generally helping out with the documentation as needed/desired.

[estruyf]

Interesting idea. Are there also some extensions already in the marketplace that provide the same experience? This would be an option to team up, or do you think it would be better if Front Matter comes with it out of the box?

@michaeltlombardi, you are welcome to be part of the team to improve Front Matter.

[michaeltlombardi]

On Joining the Team

I'm certainly very happy to join the team to work on Front Matter, especially given how heavily I'm planning to make use of it (and how much I really, really enjoy using it for my personal projects)!

My primary role these days is as a technical writer, but I have a background in automation engineering and developer experience. Unfortunately, my weakest code skillset is front-end, but I'm happy to learn and grow (which I need to do for some of my own projects anyway).

For this contributor style guide, I think it might fit usefully into a broader contributor guide, which I think we'll be able to feel our way around and write out as I onboard to helping more with the project, instead of just rapid firing ideas at you 😅

I'd be happy to submit a PR for markdownlint first, with an explanation of the rules it enforces so we could talk through them and settle on a first pass, then apply those rules to the project.

The Vale configuration I think requires more conversation, because while it's pretty easy to decide on the right way to do syntax, grammar and voice is a little more difficult.

In my experience, one of the benefits of going through this process is that it also forces us as maintainers to take a fresh look at our documentation and is a great opportunity to rewrite/expand/etc as we go (or, at least: file issues for ourselves to address that work in the future).

On Vale and Markdownlint in Front Matter

There are extensions for both markdownlint and Vale - I use them in my day job and for my personal sites.

I think in the first pass, I meant for this issue to apply primarily to this repository, so I can better understand how to help out with documentation (and we can have some assurance on voice and syntax consistency).

That being said, I absolutely see some really good room for integrating these tools with Front Matter, perhaps in the form of commands or exposing some of the info Vale gives us about or documents in the Front Matter Editor Panel, like SEO.

For example, Vale's Readability package can inspect documents for some useful metrics that folks might want to know about, and it can report that information as JSON:

JSON Output from Vale

{
  "content\\games\\66\\publishing.md": [
    {
      "Action": {
        "Name": "",
        "Params": null
      },
      "Check": "Readability.FleschReadingEase",
      "Description": "",
      "Line": 1,
      "Link": "https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests",
      "Message": "Try to keep the Flesch reading ease score (66.01) above 70.",
      "Severity": "warning",
      "Span": [
        1,
        0
      ],
      "Match": ""
    },
    {
      "Action": {
        "Name": "",
        "Params": null
      },
      "Check": "Readability.LIX",
      "Description": "",
      "Line": 1,
      "Link": "https://en.wikipedia.org/wiki/Lix_(readability_test)",
      "Message": "Try to keep the LIX score (36.31) below 35.",
      "Severity": "warning",
      "Span": [
        1,
        0
      ],
      "Match": ""
    },
    {
      "Action": {
        "Name": "",
        "Params": null
      },
      "Check": "Readability.SMOG",
      "Description": "",
      "Line": 1,
      "Link": "https://en.wikipedia.org/wiki/SMOG",
      "Message": "Try to keep the SMOG grade (10.56) below 10.",
      "Severity": "warning",
      "Span": [
        1,
        0
      ],
      "Match": ""
    },
    {
      "Action": {
        "Name": "",
        "Params": null
      },
      "Check": "Readability.ColemanLiau",
      "Description": "",
      "Line": 1,
      "Link": "https://en.wikipedia.org/wiki/Coleman%E2%80%93Liau_index",
      "Message": "Try to keep the ColemanΓÇôLiau Index grade (9.75) below 19.",
      "Severity": "warning",
      "Span": [
        1,
        0
      ],
      "Match": ""
    }
  ]
}

That information could then be presented usefully to content authors and maintainers, updated when they save or open their file.

[estruyf]

I believe you are a perfect fit for Front Matter to grow and help others. 😊 Your invitation is on its way to you.

I now also better understand what you want to do with both extensions. As you said, let us first focus on the documentation and be a good example.

Looking forward to the PR 🙏