Ideas for "next time"

[sypets]

These are currently just "ideas". They are not finalized yet and we might reject them later.

The idea is to have the "Extension Award" for every LTS release (starting shortly after), but not focus primarily on documentation every time, e.g. next time focus on testing or usability or ...

Voting process

• use jury to prepick from list of nominees (to reduce nominees) before community vote, as in DSDS

• have several categories, use different selection process (e.g. community, jury, automatic and combination)

  • "general" category: community vote
  • documentation: jury pick
  • number of contributors: automatic
  • number of downloads / time: automatic
  • testing: combination of automatic (e.g. test coverage) and jury

• maybe keep one category for next time and have one new category. That way you do not have too many categories for one time (e.g. 2 or 3) and they can alternate.

Aquire additional feedback

• vote or rate for specific aspects of the documentation so we have some results / statistics to determine what is perceived as helpful / not helpful for documentation and can be used to improve other documentation as well (possibly separate voting and giving feedback as separate process where the "giving feedback" part does not necessarily have to be connected to a login on my.typo3.org and could be a longterm thing)

Other

• create a list of quality criteria for documentation to be used as help. It can be like a checklist, e.g.
  • structure clear, menu, easy to find stuff
  • includes installation and setup instructions
  • appropriate use of formatting (e.g. code blocks)
  • no formatting errors (e.g. warning.txt empty)
  • Easy to read and skim, e.g. short paragraphs, appropriate headers etc.
  • Is helpful (documentation that is useful for using extension)

[alexander-nitsche]

Having read all nominated documentations of 2021, these are my list of criteria extracted from the notes i took from the review:

1. being registered for rendering and deployment to docs.typo3.org in intercept and linked accordingly on TER extension page (important for being found in the new docs.typo3.org internal global search)
2. preventing documentation maintenance in two places (reduce one to minimum with abstract and links to TER / VCS / docs.typo3.org and write documentation in the other)
3. having good abstract (short but well explaining the purpose - with keywords)
4. having good and clear menu structure
5. preventing subpages of few lines (merge with sibling pages as sections into parent page instead)
6. having clearly separated content (page "Installation" should not contain parts of "Configuration" page)
7. having introduction page (longer than abstract, showing example input + output, enriched with screenshots or diagram, should give enough information to new user to decide whether that extension may be selected)
8. having installation page for composer mode and legacy mode
9. having configuration page
10. having contribution page
11. guiding the user in vertical direction from global scope (where in the TYPO3 context is this extension's place) to concrete parts of the extension (steps in backend modules, steps in configuration, steps in programming, API reference)
12. guiding the user in horizontal direction by comparing this extension to similar ones of the TER and expose its benefit
13. having a good balance between text and headers and pictures and diagrams and code blocks and menus
14. no page should contain only a menu: there should always be text guiding the user
15. having a good balance of internal and external links (not too many external links, ideally not linking twice to the same target, links are breaking the reader's flow)
16. no outdated links, links to official TYPO3 documentation of compatible TYPO3 version
17. preventing explanations of TYPO3 Core functionality and linking to official TYPO3 documentation instead
18. linking generally to other extensions in TER instead of GitHub / Packagist etc. as the TER page bundles those links
19. consistent formatting (listing properties on page A in style A and on page B in style A too, no shrinked / stretched screenshots, no too-many-too-narrow-table-columns)
20. consistent terminology (writing of "view helper" on page A should not be switched to "ViewHelper" on page B)
21. consistent language (everything should be in english, even the screenshots, deepl.com is your friend)

and some documentations that meet many of these criteria in 2021 are

• External Import (author François Suter is former TYPO3 Documentation Team leader)
• Structured data with the schema extension (author is Chris Müller)
• Matomo Widgets (author is Chris Müller)
• Mask (author is Gernot Ploiner)

[sypets]

"quality criteria", created new issue for this: https://github.com/sypets/typo3-extension-documentation-award/issues/14

However, this should probably be continued elsewhere. But we can use that issue for now.

I noticed, it is difficult to review existing documentation without a "checklist"