[OSPO Book] Prepare a standard for written content

[alice-sowerby]

@alice-sowerby and @fer-correa will research and propose a standard for written content to help support authors and reviewers in producing consistent content.

• Look at some existing standards/guides
• Propose a standard

[koozz]

We could create the TODO Group style in Vale (which is also used in the workflows to check on a combination of proselint and alex at the moment. Google, Microsoft, and RedHat have Vale styles based on their Style Guides. This can be very elaborate, like writing everything in an active voice (which might suit technical documentation better?). The style can be configured in rules that Vale can automatically check on each pull request. The warnings and errors can be configured to not prevent a merge of a pull request, but they can comment on the pull request for the author and reviewers to see.

[alice-sowerby]

@koozz this looks really helpful. Having a way to embed the style into the GH workflow could provide timely and automated feedback to writers and support the reviewers/editors in their work.

It would be helpful if we could reuse something from another project.

• The Google developer documentation style guide looks appropriate as it encourages clear and direct writing.
• The Microsoft Writing Style Guide seems less of a fit, and is more heavily focused on brand voice and has a pre-sales feel.
• The Red Hat Supplementary Style Guide could be appropriate but is hard to assess as it has to be reviewed in combination with the IBM Style Guide.

If we wanted to re-use the Google Vale style, could we test it on the existing content and see whether we like the output?

[koozz]

@alice-sowerby, sure, you can also test it locally (way faster than the GitHub workflow feedback loop). I'm a Neovim user, but chances are that Visual Studio Code is easier to grasp for a wider audience.

1. Install Visual Studio Code.
2. Make sure to install Vale locally:
   • Windows: choco install vale
   • macOS: brew install vale
   • Linux: snap install vale
3. Install VS Code plugin:
   • VS Code: https://marketplace.visualstudio.com/items?itemName=chrischinchilla.vale-vscode
4. Restart VS Code.
5. Update the vale.ini
   • with Packages = Google (can be added in the comma separated list).
   • with BasedOnStyles = Google (can be added in the comma separated list).
6. Run the command vale sync to download the Google style (once).
7. Open a markdown file and find (or create) an error.

The review-docs workflow will work with the "vendored" files to prevent a vale sync and download on every workflow run. The Google style can be added to GitHub or we can derive a new style.

[alice-sowerby]

Thanks @koozz I'm not a developer so most likely I will hit some problem trying to follow the instructions you gave. But I think @fer-correa may have more luck.

[fer-correa]

Thanks @koozz for everything you shared, a beginners guide to follow. I appreciate it.
@alice-sowerby, I'll be back with news.

[koozz]

I ran vale sync locally (in the ospology repository) and the alex-style was updated with OCD.yml. In the screenshot you can see the project, on the right side the rule that was freshly added (not committed to the repository yet), in middle I tested this rule by adding a sentence with OCD in it. It showed a nice squiggly line underneath and the "problems"-pane at the bottom shows the error as well.

It already works locally if you install these tools and it works in the workflow with the current styles. I'm looking forward to create a TODO Group style 👍

[fer-correa]

everything works fine @koozz

Yeah, about to create a TODO Group style... It's really exciting that we can have it.

[alice-sowerby]

I would like to see the output of running the Google on the OSPO book so that I can assess whether we need to amend the Google style in any way.

@koozz, I will be meeting with @fer-correa next Tuesday to look at this together. Let me know if you would like to join us.

[koozz]

@alice-sowerby, @fer-correa, with the style changed to Google (and after running vale sync):

The output is as follows (when running vale [--output JSON] ospo-book/content/en/ > vale-google-style.(txt|json)

• vale-google-style.txt
• vale-google-style.json

I see there's some color coding in the text file, not very readable, sorry for that. If you run cat vale-google-style.txt you get the terminal output with the colors.

[alice-sowerby]

From @koozz:

The infrastructure is already there [to integrate with Gh workflows], see: https://github.com/todogroup/ospology/pull/535/files for example. It shows some "alex.Condescending" and "Vale.Spelling" errors as hints. There's one caveat, GitHub will stop reporting any errors above 10, any warnings above 10 and any notices above 10. At most you can show 30 messages (error+warning+notice). When you fix these and the pull request automation runs again, the "new" errors will pop-up.
We can remove, adjust, or keep the condescending check. It is stored in the repository as well: https://github.com/todogroup/ospology/blob/main/.vale/alex/Condescending.yml
We can start with the Google styleguide, mix in some "alex" and "proselint" to our own needs and brand it as TODO (with the right CC-BY-4.0 references to the Google, Alex and Proselint styles).

[alice-sowerby]

@anajsana before we get too far creating our style, is there a LF style we can adopt? Perhaps something used for other books.

[alice-sowerby]

@fer-correa and I met yesterday. As we see it, the next steps are:

1. Create a human-facing writing guide to support writers with what they should be aiming for when writing and editing content for the book (if there is a LF or other existing guide suitable, we should use this or adapt it if needed).
2. Amend/create the YML files to support an automated check of written content.
3. Set up a method for testing content pre-commit/PR so writers can check their work while developing content.
4. Set up a method for testing content as part of the GH workflow (already possible as mentioned by @koozz
5. Test existing content and amend it to pass tests.
6. Create docs/induction for contributors who want to create new content.