Sharing DITA compatibility requirements upstream

[Lennonka]

DITA migration has specific requirements for the structure and markup that we must adhere to.

I think it would be useful to share these requirements upstream. I'm not sure how to do that - paste them into an issue and link them to a README?

We also have specific Vale styles for this purpose. Would anyone object against incorporating them into our Vale check?

@theforeman/documentation

[maximiliankolb]

I don't object to extending the vale checks per se, but I'd like to see them on a feature branch first to get a better feeling for the results. If it's too much noise, then I'm leaning towards changing the docs first and adding the check afterwards. If not, then 👍

[Lennonka]

@maximiliankolb We're definitely going to fix the docs first and add the check afterwards. It would be too much noise at the moment.

[aneta-petrova]

Would asciidoctor-dita-vale's readme work as the list of requirements? https://github.com/jhradilek/asciidoctor-dita-vale

Other than that, I'm in favor of extending the Vale checks with the DITA requirements once we reach a point where it wouldn't generate too much noise.

[Lennonka]

@aneta-petrova Oh yeah, the Available rules list them. That's a good idea.

[Lennonka]

Thanks for your comments!

Btw, there's one issue with incorporating the DITA checks into our Vale styles: the required severity level of checks for DITA is "warning" whereas we currently use "suggestion". I'm not sure how to resolve that.

Suggestions for DITA would generate extreme noise in our case.

cc @apinnick

[apinnick]

@Lennonka The 'suggestion' level for displaying checks is set in our .vale.ini file. If you added the DITA Vale package to the .vale.ini file, it would inherit the display level. 'error' level alerts cause the PR to fail. 'warning' and 'suggestion' do not.

In addition, the severity levels of the individual rules (error, warning, suggestion) are also set in the Vale rules within the package. I'm not sure you could override their levels because Vale sync pulls in the package each time you run it.

Honestly, the only way to find out is to create a test PR.