Define general structure of a manual

[sypets]

Problem

Currently, most manuals follow a general structure, but there are various differences.

Some of the following issues have been raised / suggestions been made by people from the community as feedback:

• startpage: it often contains information, that is redundant (e.g. already located in footer or left panel) or is not relevant for the reader (e.g. version, copyright, rendered on).
• Often, the reader has to skip to page 3 (past the sitemap) before he even finds out what the manual is about. Sometimes you even have to scroll through a Table of contents and then through a sitemap (e.g. Frontend Localization Guide)
• Some manuals do not provide important information at all (e.g. what is manual about)
• The page "link targets" or "Targets for cross referencing" is cryptic for the reader and only required for people editing.
• The start page is not visually appealing
• structure is not always consistent:
  • example: Introduction section: sometimes information about the topic of the manual is found in introduction, sometimes general information like (feedback, thank you section etc.)
  • example: "What does it do" : Sometimes it is in Introduction (e.g. [ext:solr] (https://docs.typo3.org/typo3cms/extensions/solr/Introduction/Index.html)) sometimes on startpage (e.g. ext:tika)

Possible solutions

Here are some ideas but this needs to be refined and decided.

In general, different but similar guidelines should be found for extensions, guides, tutorials and references.

• Add tile optic with images on startpage as suggested here: Rework start page and menu structure DocsTypo3Org-Homepage#22
• Decide what information should be on the start page and should come first. Suggestion:
  • What is the manual about?
  • What are the prerequisites?
  • What is the target audience
  • Some quicklinks
• Remove "link targets" from menu
• Add a Quickstart page, as done here: https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Logging/Quickstart/Index.html#logging-quickstart
• Define best practice of general structure of manuals (e.g. startpage, Introduction, etc.)

Information

• template for extension manual

[sypets]

Some of the issues raised have already been decided and solved, see also start page

startpage: it often contains information, that is redundant (e.g. already located in footer or left panel) or is not relevant for the reader (e.g. version, copyright, rendered on).

resolved, information located in footer is now removed

Often, the reader has to skip to page 3 (past the sitemap) before he even finds out what the manual is about. Sometimes you even have to scroll through a Table of contents and then through a sitemap (e.g. Frontend Localization Guide)
Some manuals do not provide important information at all (e.g. what is manual about)

Description should be on the top.

The page "link targets" or "Targets for cross referencing" is cryptic for the reader and only required for people editing.

Is now removed from main menu, is included on start page in a sidebar "Contributors", see start page

The start page is not visually appealing

structure is not always consistent:
example: Introduction section: sometimes information about the topic of the manual is found in > introduction, sometimes general information like (feedback, thank you section etc.)

That is still a todo - unify what is in Introducion - the sitepackage tutorial puts the "about" content in a preface and contains an "Introduction" page with an introduction to the topic. I think we should go with that.