Following up on a discussion with @danbri and @gmackenz in PR #4674

According to the currently published documentation example files require the related issue number inside the example file:

The first value in the TYPES line is the key used for this example, use the bug number with a # prefix, the following comma separated values identify the types the examples apply to.

In the attempt to revive the webAPI PR a progressive number was present that did not align with the documentation which in fact was confirmed by @danbri being an alternative numbering scheme with progressive numbers citing that tagging examples with the progressive number could easily be done through a Python script.

I'd like to align the current documentation with what's the current state so following questions came up:

• Right now there seem to be two different MOs existing in parallel (issue number and progressive numbering), which one is correct or if both, when do I pick what?
• the documentation does currently cite the existence of the software/SchemaExamples/schemaexamples.py which to me was completely new that seems to schema "lint" the example files including the provision of unique IDs. Is that still required or desirable?

If we manage to solve those two questions I would actually sit down and write docs for that.

Personally I would add one consideration: while git is an open standard, GitHub is not. Some considerations should be made if issue numbers would persist a platform migration if they ever have to or if providing a better file structure braking out classes, properties et cetera into single files might not be a better long term strategy to provide easy navigation. This would probably also require more discipline on commit messages.