[DONE] Proposal for documentation manual start page

Result (Dec 26, 2020): Will implement as proposed.


Goal of decision: Get feedback on this proposal, agree on start page.


We recently decided to remove “Link targets” from the main menu and place the link on the start page (because the info is only relevant for editors and goal is to declutter menu). Problem is, where to put it.

I find it important to have a unified start page which will make it easier for orientation. We had that, meaning most of the start pages follow a specific template, but this has partly deviated and is also partly obsolete, meaning some of the information is actually unnecessary or outdated.

I would like to make a new proposal for a start page:

What should be on the start page:

meta information

Goal: keep meta info as short as possible so other relevant information is not off screen

  • version - as that is now visible on the top of every page via the version selector - even on mobile
  • language: should still be displayed as is not displayed via version selection, e.g. https://docs.typo3.org/p/quizpalme/camaliga/master/de-de/#discuss-topics
  • keyword: I would remove this and instead add information about target audience
  • copyright is in footer
  • license: is not in footer
  • author: can be e.g. “Documentation Team” or “Core Team” or “Core Team & community” and link to contributors on GitHub or a section in the manual with credits
  • Previous Key: : was used to identify extension (docs used to be in extension), we decided to remove this a while ago
  • Email - not necessary, contact email is in footer
  • Rendered: Date / time not necessary, is in footer

see


Also on start page:

Text that is no longer correct:

This document is included as part of the official TYPO3 documentation. It has been approved by the TYPO3 Documentation Team following a peer- review process. The reader should expect the information in this document to be accurate - please report discrepancies to the Documentation Team Official documents are kept up-to-date to the best of the Documentation Team’s abilities irrelevant

  • should create an issue or PR instead.
  • is usually not only or primarily “Documentation Team” which maintains the manuals - this maintains the expectation that “Documentation Team” should fix all problems

etc.

Further work

  • as a next step a universal menu can be defined, e.g. with Sitemap always as first or last item (whichever is best) etc.
2 Likes

The change has now been merged in the TCA reference. Other manuals will be updated.

The manual “Writing Documentation” was updated and now contains a page “Examples” with some example texts.

1 Like