TL;DR
If the text below is too long for you, please just give some feedback here about how content is structured on a page on docs.typo3.org, including
- how much content is on the page
- how the content is formatted and styled (e.g. sections, lists, code blocks, images, steps with big numbers)
- Is it easy to follow the steps?
- Is it easy to see what is a subsection and where one sections ends and another starts?
- is it well readable (concerning the structure and the styling)?
Very helpful would be if you have a good example and a bad example and explain what you find good and helpful and what not.
Goal of this decision
Structuring content well on the page makes it easier to read and also makes it easier to skim (=quickly glance over it) and find relevant content on a page. The goal of this decision is to agree on general principles and best practices for structuring content and formatting on a page.
Problems
It was already mentioned on Slack and elsewhere (and also one of the points in the Vision 21 mentions this):
- when there are sections and subsections it is often difficult to see what is a section and what is a subsection (specifically the hierachy is difficult to see when glancing through the page)
- some subsections, (often specifically the properties) are too long
- it is difficult to see where one thing ends and another starts
- pages are often littered with notes and look very cluttered and visually distracting
- while we used to have too short pages and (e.g. consisting of 1 paragraph) we now tend to put too much on one page. - you see this tendency elsewhere too: But the good examples are well structured so it is not a problem.
- images with no shadow or not enough padding which include text and visibly blend with the text.
Sometimes, the structure on a page is like this:
- section 1
| - subsection 1
- section 2
Or even this:
- section 1
| - step A
| - step B1
| - OR step B2
- section 2
Or this:
- property 1
| Information for property 1
| Examples for property 1
-> subproperty 1.1.
- property 2
But this internal structure is difficult to grasp by glancing through the page.
Other documentation often has
- All on one page, but also compacter pages, meaning it is well structured and does not contain too much content
- The formatting is helpful, not distracting
I actually think some of the changes we have been making recently have made the situation worse. That is:
- Creating “monster” pages - while in the past we often had too many subpages and pages with little content. We now often have pages where everything is munched together - individual steps, more details, some notes etc.
- replacing the
.. container:: table-rowproperties formatting which was considered helpful and is now being replaced by simple definition lists with very little styling.
My suggestions:
-
A do not create huge “monster” pages - especially for things where there are several parallel paths (e.g. you can do A, then B1 or B2 and then C etc.).
-
B Use short compact 1, 2, 3 steps and possibly link to more details. Examples:
-
C Choose a good formatting scheme for properties - there is an issue: and there was a discussion on this, but very little or rather no feedback from users.
- Examples for “old” style: (
.. container:: ts-properties - Examples for new (simple definition lists):
- Examples for “old” style: (
-
D Also, think about how the sections on a page can be handled - is the “PAGE CONTENTS” in the menu really the best solution? Or / and should we have automatically generated list of sections (e.g. properties) on the top of the pages, such as on FLUIDTEMPLATE
-
E Do usability tests for these type of things (for the theme and for the formatting) or at least a small survey with a broader audience
-
F Do not use more than one admonition (note, important, warning, etc.) on (roughly) content that will be visible on the screen at once.
- Example for too much: Install TYPO3 Without Composer — Installation and Upgrade Guide 10.4 documentation
I recently looked at the news documentation, specifically the TypoScript page and I quite liked it. But I am afraid what I liked are things that are being dropped in the official docs:
- list of properties on top
- each property with a grey background box so you have a very clear separation between the properties - this is a styling that is being dropped from the official docs if I am not mistaken.