FlowFuse/handbook

Cross repo spell checking (linting of markdown)

Closed this issue · 3 comments

Pezmc commented

Epic

No response

Description

As a:

Developer / Team Member

I want to:

Be easily able to catch typos and spelling mistakes

So that:

None of our public-facing documentation or websites have mistakes.

Proposed solution:

We have documentation as markdown files across several repos (including the handbook, flowforge/docs and website) that end up public facing.

While I see @ZJvandeWeg started #75, I'd propose using a tool designed for spell-checking code such as cspell instead.

CSpell comes pre-baked with English (GB+US), programming-related, and industry-related words. Additionally, we could use a shared cspell config and custom dictionary across our repos for any FlowForge-specific terminology.

We'd then add a lint:spelling action to the repos, and could optionally, add a github action to run that task on any open pull requests to report the status.

Possible extensions:

Using cspell and the same dictionaries to check our source code (template files, error messages, comments, etc...).

Acceptance Criteria

  • Spelling mistakes can be easily caught pre/post-commit
  • The solution doesn't get in the way of development or changes
  • FlowForge-specific words and terminology pass the checks
  • Adding additional custom words is quick and easy
  • There are no typos or spelling mistakes in our repos
ZJvandeWeg commented

@Pezmc I'm in favour of any iteration at this time. Feel free to start with this issue and deliver small improvements to stop typos

  • 👍1
Steve-Mcl commented

+1 from me with cspell & I already use the Code Spell Checker VSCode plugin (locally env)

Pezmc commented

I re-picked up work on this which is living in the following places:

However, it's currently blocked by cspell seemingly not playing nicely with npm workspaces.

CSpell should support importing the shared config from the @flowforge namespace after requiring it through npm i.e. @flowforge/cspell-dictionary/cspell-dict.json; but this doesn't seem to be playing nicely with flowforge-dev-env. This needs further investigation to understand why the workspace is tripping it up. Importing the files relatively works fine, but that's not cross environment compatible.