Layout of the start page of a manual

Documentation
#1

@jiriki introduced a new general layout for startpages, however Tom Warwick had also previously developed a new start page layout for those manuals already overhauled.

a) Tiles and introduction Text

Toms Solution looks like this:

image
image1283Ă—820 55.7 KB

b) Table, introduction Text and Doctree as list

@jikiri s idea is documented here:

https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#documentation-index-rst

It looks like this:

image
image1259Ă—763 39.3 KB

c) Table on top, tiles below

Combining the two, @jiriki put his part on top and toms part below instead of the doctree menu:

image
image1212Ă—818 49 KB

d) Tiles on top, table below

image
image610Ă—864 35.4 KB

Which solution shall we use?

#2

Personally, I don’t like the tiles. I have so scan like a Z (left → right → down/left → right → down/left …) and have to scroll which costs me some seconds more than just a list. But as there is mostly a sitemap available to scan in a linear way, I’m accepting the tiles ;-).

So, I am fine with version d (for “official” manuals) as it has the best value for the average user.

#3

I like a) (Tiles and introduction Text) best.

#4

I think it is hard to say at this point in general. I like the tiles but what do we do in TYPO3 Explained which a huge list of items - having an explanation for them would be nice but you have to scroll a lot more. So, in general I would prefer the tiles - not just because of the optics, but also for the description, but not for long lists which may be better structured as hierarchical bullet lists.

#5

Some more points:

  • I suggest to split up this question into, what should be on start page and how to arrange it, visually.

  • The tiles in “Getting Started” has omitted the metadata - does this mean we do not need the information anymore, such as license, authors etc.? Or is this now somewhere else? Corrrection: the metadata is still there on the bottom, looks a bit weird to me that way.

  • About the list of metadata e.g.

Version: main
Language: en
Author: ....

I already wrote before, that I find most of that redundant: version already available in version selector. “Rendered” - can already be seen in footer and only really relevant for admins. License - used to also be in footer. But not all of it.

1 Like
#6

I also think version, language and last rendered are redundant. License would belong in the footer as it applies to all pages not just the start page

1 Like
#7

And Author - I would rather have that information on an “About” page and then we wouldn’t really need the meta-data to clutter up the top of the start page anymore

1 Like
#8

What we currently use in most manuals is (b). That’s dozens of official manuals and hundreds of third-party manuals.

Introducing a second official layout with tiles instead of the table of contents is fine in my opinion, but we should point out when we want to use which one. My opinion on this is:

  • TOC: For many main menu items.
  • Tiles: For a few main menu items where the titles are intuitively clear to the normal reader. It should not end in endless scrolling, especially on mobile devices.

The second decision relates to metadata: I echo Sybille: “The metadata […] down there looks a bit weird to me.”. It looks like a programmer solved a UX problem on-the-fly. My opinion on metadata is:

  • It should be at the top of the document, especially for mobile device users who would otherwise have to scroll all the way down.
  • They shouldn’t take up too much vertical space so that the reader can immediately see the abstract text of the manual, which has been accomplished by removing things like “keywords” etc. in recent documentation standard runs.
  • It should be of value to the reader, which is accomplished by allowing the reader to take a quick look at the state of the manual before diving into it: Has it been rendered recently or is it likely to be out of date, has the correct manual been loaded or is the version switch broken, for which extension key and package name is this manual correct, and so on. Such a check after reading the summary and table of contents/tiles would sometimes waste the reader’s time unnecessarily.
  • It should follow the best practice of other types of documentation, such as a dissertation, letter or email, where the metadata is at the top and then the abstract/subject and text.

In any case, any change to the documentation should be documented in the documentation standard and applied to all official manuals.

#9

+1 on removing the metadata.

I’m okay with the tiles, but they don’t work for long lists (like in TYPO3 Explained). Could we have a rule? 6 tiles is okay, but >6 use with a bullet list. I’m not sold on that.

I’m not sure what the answer is here. :woman_shrugging:

1 Like
#10

I also prefer solution a) and support removing the meta data from the start page.