You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Documentation/80GuidesRegistry/Index.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Guides Registry
2
2
3
-
The full list of step-by-step guides. See [How to Place Guides in the Registry Structure](../90Contribute/20ContributorGuide/50PlaceGuidesInTheStructure.md) to add a new guide.
3
+
The full list of step-by-step guides. See [How to Place Guides in the Registry Structure](../90Contribute/30UnderstandingTheStructure/20PlaceGuidesInTheStructure.md) to add a new guide.
-[Links between step-by-step guides and the TYPO3 documentation](#links-between-step-by-step-guides-and-the-typo3-documentation)
4
+
-[From step-by-step guides to the TYPO3 documentation](#from-step-by-step-guides-to-the-typo3-documentation)
5
+
-[From the TYPO3 documentation to step-by-step guides](#from-the-typo3-documentation-to-step-by-step-guides)
6
+
-[How to find a guide or documentation page to link to](#how-to-find-a-guide-or-documentation-page-to-link-to)
7
+
-[How to link to missing guides](#how-to-link-to-missing-guides)
16
8
17
-
The following sections are optional but strongly encouraged:
18
9
19
-
***Resources** — Links to supporting material
20
-
***Video** — Embedded video version of the guide (from the official TYPO3 YouTube channel)
10
+
Guides don’t exist in a vacuum, and linking to and from other content multiplies their usefulness. For step-by-step guides, there are two main document types to interlink with: the encyclopedic TYPO3 documentation, and [SkillDisplay](https://www.skilldisplay.eu/) skills.
21
11
22
-
<br />
12
+
## Links between step-by-step guides and the TYPO3 documentation
23
13
24
-
Use the [template](../10Template/Index.md)and [writing instructions](30UsingTheTemplate.md) to complete each section.
14
+
Step-by-step guides and encyclopedic documents should link to each other, in both directions.
25
15
26
-
All required sections must be complete and free of placeholders like “TBD.”
16
+
### From step-by-step guides to the TYPO3 documentation
27
17
28
-
Every guide will have room for improvement — that’s expected. That’s why all TYPO3 step-by-step guides include a feedback section to collect reader-reported gaps and issues.
18
+
Step-by-step guides should point to relevant documentation pages for these reasons:
29
19
30
-
# Definition of done
20
+
- To let the reader go into details if needed
21
+
- To avoid repeating content that is already available
22
+
- To keep the guides focused on the task
31
23
32
-
A step-by-step guide is ready for submission when:
24
+
Inside a guide, linking to the documentation can be done in three ways:
33
25
34
-
[] All required sections are complete — no placeholders.
35
-
[] Numbered steps are logical, testable, and lead to the expected outcome
36
-
[] Screenshots or code examples are included where appropriate and follow TYPO3 guidelines.
37
-
[] Relevant concepts or references are linked where needed
38
-
[] Language is clear, concise, and action-oriented
39
-
[] The guide has been tested by the author
40
-
[] The guide follows [TYPO3 writing conventions and formatting rules](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/ContentStyleGuide.html)
41
-
[] The guide fits its intended scope. (One learning objective per guide, or a project guide for more complex, multi-step processes.)
26
+
- Within the text, as embedded links
27
+
- As a callout after a paragraph, such as:
42
28
43
-
# How to link to missing guides
29
+
`For a complete overview of TypoScript options, see the [TypoScript reference].`
30
+
31
+
- At the end of the guide, the Resources section can contain accumulated links to the TYPO3 documentation.
32
+
33
+
### From the TYPO3 documentation to step-by-step guides
34
+
35
+
The opposite direction, from the documentation to step-by-step guides, is equally important, as it can prevent beginners from choosing the wrong kind of documentation for starting their journey of learning TYPO3.
36
+
37
+
If a step-by-step guide exists for a given page of the documentation, this page or section should contain a “guide available” banner:
38
+
39
+
`Step-by-Step Guide Available`
40
+
41
+
`Learn how to implement this feature with our step-by-step guide: [Creating Custom Content Elements]`
42
+
43
+
## How to find a guide or documentation page to link to
44
+
45
+
** Do a search **
46
+
47
+
* Check the [Step-by-Step Guide registry](../../80GuidesRegistry/Index.md)
48
+
* Use the [TYPO3 Documentation search function](https://docs.typo3.org/search/) - it is powerful and comprehensive. Try a few different terms or phrasing variations.
49
+
50
+
If your search turns up nothing useful, that may be a good sign that your guide really is needed.
51
+
52
+
**See what others have done**
53
+
54
+
Look at step-by-step guides written by other contributors that sit before or alongside yours in the structure. See what documentation pages they link to. This saves you the trouble of searching the docs from scratch.
55
+
56
+
If your guide builds on or shares a task with a similar guide, chances are it will already have referenced the same concepts, terminology, or documentation pages that you’re looking for. For example, creating pages, adding content elements, accessing page properties, etc.
57
+
58
+
## How to link to missing guides
44
59
45
60
Sometimes, while writing a step-by-step guide, you’ll need to reference a related guide that doesn’t exist yet. This might happen:
46
61
@@ -54,25 +69,10 @@ That’s okay! Missing guides are part of a growing system, and it’s important
54
69
Add a note in the PR that your guide references non-existent guides.
55
70
56
71
2.**Add the missing guide to the structure.**
57
-
Don’t worry about writing the guide yourself — just give it a logical placeholder. See [How to Place Guides in the Structure](50PlaceGuidesInTheStructure.md) for more information.
72
+
Don’t worry about writing the guide yourself — just give it a logical placeholder. See [How to Place Guides in the Structure](../30UnderstandingTheStructure/20PlaceGuidesInTheStructure.md) for more information.
58
73
59
74
**Missing guides will be tracked automatically in the future.** In the future, an automated script will help us keep track of missing guides.
60
75
61
76
We plan to add an automated script that periodically scans for links to step-by-step guides that don’t yet exist—essentially, broken internal links within the repository. These will be flagged for review so they can be confirmed and added to the structure.
62
77
63
-
We may also collect unplaced guides in a “pending” section at the bottom of the [Step-by-Step Guide registry](../../80GuidesRegistry/Index.md) to be filed manually. This will help us maintain a living, evolving guide library where contributors can spot gaps, reserve titles, and grow the system collaboratively.
64
-
65
-
# How to find a guide or documentation page to link to
66
-
67
-
#### Do a search
68
-
69
-
* Check the [Step-by-Step Guide registry](../../80GuidesRegistry/Index.md)
70
-
* Use the [TYPO3 Documentation search function](https://docs.typo3.org/search/) - it is powerful and comprehensive. Try a few different terms or phrasing variations.
71
-
72
-
If your search turns up nothing useful, that may be a good sign that your guide really is needed.
73
-
74
-
#### See what others have done
75
-
76
-
Look at step-by-step guides written by other contributors that sit before or alongside yours in the structure. See what documentation pages they link to. This saves you the trouble of searching the docs from scratch.
77
-
78
-
If your guide builds on or shares a task with a similar guide, chances are it will already have referenced the same concepts, terminology, or documentation pages that you’re looking for. For example, creating pages, adding content elements, accessing page properties, etc.
78
+
We may also collect unplaced guides in a “pending” section at the bottom of the [Step-by-Step Guide registry](../../80GuidesRegistry/Index.md) to be filed manually. This will help us maintain a living, evolving guide library where contributors can spot gaps, reserve titles, and grow the system collaboratively.
Sometimes, the task is basically the same — but not quite. Installing TYPO3 on Windows isn’t that different from doing it on Ubuntu. Apache and Nginx both serve pages just fine. But the commands, quirks, and gotchas? They diverge fast.
4
+
5
+
So how do we write guides that are helpful without repeating ourselves endlessly?
6
+
7
+
TYPO3 step-by-step guides follow a **single-path principle**, so we create one guide per software scenario. This brings SEO opportunities but does increase the risk of content duplication and maintenance.
8
+
9
+
## One guide per scenario — optimized for SEO
10
+
11
+
***SEO visibility**: Each guide title becomes a unique, keyword-targeted entry point.
12
+
***Clarity:** One guide, one clear path — no branching or conditional steps.
13
+
14
+
Example hierarchy:
15
+
16
+
<pre>
17
+
└── Getting Started
18
+
└── Installation
19
+
└── Local Development Environments
20
+
├── Install TYPO3 on macOS with DDEV
21
+
├── Install TYPO3 on Windows 11 with DDEV
22
+
└── Install TYPO3 on Ubuntu 22.04 with DDEV
23
+
</pre>
24
+
25
+
Or:
26
+
27
+
<pre>
28
+
└── Advanced Implementation
29
+
└── Deployment and DevOps
30
+
└── Server Stack Scenarios
31
+
├── Install TYPO3 with Apache and MySQL
32
+
├── Install TYPO3 with Nginx and MariaDB
33
+
└── Install TYPO3 with Caddy and PostgreSQL
34
+
</pre>
35
+
36
+
To boost SEO further, use **long-tail keywords** in the title and conceptual overview. For example: “This guide walks you through how to install TYPO3 CMS on Ubuntu 22.04 using Composer and DDEV — ideal for developers working in a Linux environment.”
37
+
38
+
We can also **cross-link to related guides**, for example, “Using macOS instead? See our macOS installation guide.”
39
+
40
+
## Extract shared tasks into atomic guides
41
+
42
+
Instead of repeating similar chunks across guides, we’ll use **modular content reuse** strategies to minimize duplication.
43
+
44
+
For example, for “nstall TYPO3 on Windows 11 with DDEV”, we might:
45
+
46
+
- Create one atomic guide for “Install DDEV on Windows 11”
47
+
- Create another for “Run the TYPO3 browser-based installer”
48
+
- Link both into the OS-specific guide, which focuses on the Windows-specific context
The following sections are optional but strongly encouraged:
20
+
21
+
***Resources** — Links to supporting material
22
+
***Video** — Embedded video version of the guide (from the official TYPO3 YouTube channel)
23
+
24
+
<br />
25
+
26
+
Use the [template](../10Template/Index.md) and [writing instructions](30UsingTheTemplate.md) to complete each section.
27
+
28
+
All required sections must be complete and free of placeholders like “TBD.”
29
+
30
+
Every guide will have room for improvement — that’s expected. That’s why all TYPO3 step-by-step guides include a feedback section to collect reader-reported gaps and issues.
31
+
32
+
## Definition of done
33
+
34
+
A step-by-step guide is ready for submission when:
35
+
36
+
[] All required sections are complete — no placeholders.
37
+
[] Numbered steps are logical, testable, and lead to the expected outcome
38
+
[] Screenshots or code examples are included where appropriate and follow TYPO3 guidelines.
39
+
[] Relevant concepts or references are linked where needed
40
+
[] Language is clear, concise, and action-oriented
41
+
[] The guide has been tested by the author
42
+
[] The guide follows [TYPO3 writing conventions and formatting rules](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/ContentStyleGuide.html)
43
+
[] The guide fits its intended scope. (One learning objective per guide, or a project guide for more complex, multi-step processes.)
0 commit comments