How to structure content on a page

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.


Problem

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.

Meaning, 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-row properties formatting which was considered helpful and is now being replaced by simple definition lists with very little styling.

My suggestions:

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.

I definitely liked the old way much better! It is far easier to apply “pattern matching” in your eyes to spot the information you need, like a default value.