Editor guidelines for text content

[jmuheim]

TODO: create or add to GUIDELINES.md!

We need editor guidelines, probably as bare GUIDELINES.md (or CONTRIBUTION.md?) file in the repo (not in the compiled ADG).

General:

• We generally link to the most recent version of the WCAG spec. At the moment this is the WCAG 2.1 Guidelines
• For the few cases where the ADG gives recommendations which are specifically based on one of the new rules introduced in 2.1 we mention that. We keep it “timeless”, e.g. we don’t say “according to the new WCAG 2.1 guidelines …”, rather “according to the WCAG 2.1 guidelines…” or “according to the WCAG guidelines (version 2.1)…”

Language:

• Simple (short sentences, no relative sentences, no passive)
• Bullet points when appropriate
• Aimed at techies, but not too "geeky"
• Language (currently British, e.g. colour instead of color)

Technical:

• Special chars ("test" vs. „test“, etc.)
• Etc.

Images:

• PNG
• Need proper descriptive alternative text
• File names reflect the alternative texts as closely as possible (in a "sluggish" way)
  • E.g. ![This is a file!](_media/this-is-a-file.png)
• Original files (Photoshop etc.) should be checked in, too

Open questions:

• What defines a "Contributor"? On the "About" page, when will somebody be listed there? Only when contributing content/code, or also when working "behind the scenes" (community building etc.)?

[AndreasMoesch]

More points to clarify

• Use of bold vs. use of italic text. Currently there are no italics at all, because the text styling (and font style?) for it doesn’t exist. But there are cases where italics would make more sense. It’s typically used to add emphasis to a word in a sentence, while bold is often used to provide additional visual anchors for people who skim.
• Hyphens (-) vs. dashes (– or —) (e.g. check this article about Hpyheons Em Dashes and En Dashes)

[jmuheim]

Maria Müller gave some more interesting input about this during the last hack day, for example that we should not use abbreviations like "e.g.", "etc.", and so on. I'm sure she can add more to that soon, as she will take a look at our guide's general language and might hold a short presentation about her findings and about use of language in an accessible way in general.

[estherbrunner]

I will compile the above suggestions into a file and submit a pull request.