sartography
/
spiff-arena
mirror of https://github.com/sartography/spiff-arena.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc markdownlint

This commit is contained in:
burnettk 2023-05-19 10:54:01 -04:00
parent 69d2bb938a
commit ef8966a537
No known key found for this signature in database
2 changed files with 14 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/.markdownlint.jsonc Normal file
View File

@ -0,0 +1,5 @@
{
"default": true,
"MD013": false,
"whitespace": false
}

10
docs/documentation/documentation.md
View File

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