From 0846f355900f7904b9d17708ba0fdbc0d2fa10c1 Mon Sep 17 00:00:00 2001 From: burnettk Date: Fri, 19 May 2023 10:54:01 -0400 Subject: [PATCH] doc markdownlint --- docs/.markdownlint.jsonc | 5 +++++ docs/documentation/documentation.md | 10 +++++++++- 2 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 docs/.markdownlint.jsonc diff --git a/docs/.markdownlint.jsonc b/docs/.markdownlint.jsonc new file mode 100644 index 00000000..1095ce39 --- /dev/null +++ b/docs/.markdownlint.jsonc @@ -0,0 +1,5 @@ +{ + "default": true, + "MD013": false, + "whitespace": false +} diff --git a/docs/documentation/documentation.md b/docs/documentation/documentation.md index 347da0c7..6b0863cc 100644 --- a/docs/documentation/documentation.md +++ b/docs/documentation/documentation.md @@ -10,7 +10,7 @@ The methodology we are following is known as ["Docs as Code"](https://www.writet This means using the same tools and processes that software developers use for writing code to write the documentation for code. In following this methodology, you will have to pick up some tools you haven't had to use before (Git, Sphinx). -Why would a technical writer need to learn these software engineering tools? +Why would a technical writer need to learn these software engineering tools? I'll never make the case as well as an article by [Tom Johnson](https://idratherbewriting.com/trends/trends-to-follow-or-forget-docs-as-code.html). You might notice, when looking at the markdown files, that every sentence starts on a new line. @@ -137,3 +137,11 @@ You can do that by following these steps: 2. Press the blue "Commit" button. 3. Any changes you pushed up should be live on our website within 5 to 10 minutes. + +## Linting + +Documentation people: please ignore this for now. + +We may decide to check the documentation with a "linter" which is designed to keep the documentation consistent and standardized. +One option is https://github.com/igorshubovych/markdownlint-cli, which uses https://github.com/DavidAnson/markdownlint, which seems to be more popular than https://github.com/markdownlint/markdownlint. +A `.markdownlint.jsonc` file has been added that configures the same markdownlint program (basically to ignore the rule about long lines, since we are using ventilated prose).