Document how to write XML documentation files

[GaryJones]

Is your feature request related to a problem?

I can't find an obvious place that tells new contributors how to write new XML documentation files.

Describe the solution you'd like

A section in CONTRIBUTING.md that highlights the existing "features" of existing documentation files, such as how and when to use the <em> </em> tags, to put the valid code before the invalid code, how descriptions should be written, how to handle where there is an imbalanced number of ways to get things wrong vs getting things right, etc.

Additional context (optional)

• I intend to create a pull request to implement this feature.

[jrfnl]

@GaryJones Good point. Then again, once the ongoing "let's get the documentation written" task has been finished, there shouldn't be much need for it aside from the odd new sniff.

The documentation task issue #1722 contains reasonably detailed info on writing documentation. What do you think, would linking to that issue be enough ? Or maybe distilling the most essential bits ("guidelines" bullet point) ?

The PHPCS Contributing Guide also has a section about writing docs, which we could link to.

[jrfnl]

Maybe also relevant: for "what can go wrong", we currently have one QA check in place for the docs (though more will be added once available and two extra checks are being worked on). The current check validates that the XML docs at the very least comply with the XSD file as available from PHPCSDevTools.