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.


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):

  1. 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)
  2. some subsections, (often specifically the properties) are too long
  3. it is difficult to see where one thing ends and another starts
  4. pages are often littered with notes and look very cluttered and visually distracting
  5. 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.
  6. 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-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.

Can you add a screenshot / link which formatting you mean? Or even better for both: what you considered good and what you consider not so good.

(Screenshots because the page where we link to may change)

I think this will make it easier to follow along because there are several ways to format the properties in the field now.

Also related to formatting the properties is this issue: Cheat Sheet: Mention Definition Lists only or also good ol' table for references? · Issue #57 · TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument · GitHub

I don’t have a screenshot at hand and currently also no link to an old rendering. So let me briefly describe it.

Each property should be an easily distinguishable block and not just a header. (e.g. a guidance line on either side or even a full border around)
Each block should then have clear sub-headers for:

  • Name
  • Type
  • Description
  • Default value/behaviour
  • Introduced with version X

All of these have to be mandatory except the last, which is just an idea.

1 Like