Skip to content

Commit db20f85

Browse files
flicstarflicstar
authored
[FEATURE] Add template and contributor guide (#2)
* Create .gitpod.yml * First steps to adding contrib guide * emoji test * emoji test 2 * Add template * Getting some content in there * Create registry * Update registry * A few updates * update to registry * More tweaks * readme and intro text * Last bits * Fix probs
1 parent c827655 commit db20f85

File tree

12 files changed

+854
-1
lines changed

12 files changed

+854
-1
lines changed

‎.gitpod.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
tasks:
2+
- name: Build
3+
init: make docs
4+
command: python3 -m http.server 8080
5+
6+
ports:
7+
- port: 8080
8+
onOpen: open-browser

‎Documentation/80GuidesRegistry/Index.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Guides Registry
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.
4+
5+
### Getting Started
6+
7+
**Installation**
8+
9+
- [Install TYPO3 With Composer](../10GettingStarted/10Installation/10InstallTYPO3WithComposer/Index.md)
10+
- [Install TYPO3 Without Composer](../10GettingStarted/10Installation/20InstallTYPO3WithoutComposer/Index.md)
11+
- [Setup TYPO3 With DDEV](../10GettingStarted/10Installation/30SetUpTYPO3WithDDEV/Index.md)
12+
- [Upgrade an Existing TYPO3 Installation](../10GettingStarted/10Installation/Index.md)
13+
14+
**Basic Configuration**
15+
16+
- [Backend Basics](../10GettingStarted/20BasicConfiguration/10BackendBasics/Index.md)
17+
- [Setup a Site Configuration](../10GettingStarted/20BasicConfiguration/30SetUpASiteConfiguration/Index.md)
18+
- [Implement SiteSets (v13+)](../10GettingStarted/20BasicConfiguration/Index.md)
19+
20+
**Content Creation**
21+
22+
- [Create and Organize Pages](../10GettingStarted/30ContentCreation/10CreateAndOrganizePages/Index.md)
23+
- [Add Various Content Elements](../10GettingStarted/30ContentCreation/20AddVariousContentElements/Index.md)
24+
- [Work with the Rich Text Editor](../10GettingStarted/30ContentCreation/30WorkWithTheRichTextEditor/Index.md)
25+
- [Manage Media Assets](../10GettingStarted/30ContentCreation/40ManageMediaAssets/Index.md)
26+
27+
**Site Packages**
28+
29+
- [Create a Basic Site Package](../10GettingStarted/40SitePackages/10CreateABasicSitePackage/Index.md)
30+
- [Use the Bootstrap Package](../10GettingStarted/40SitePackages/20UseTheBootstrapPackage/Index.md)
31+
- [Customize Templates](../10GettingStarted/40SitePackages/30CustomizeTemplates/Index.md)
32+
- [Implement Your Design](../10GettingStarted/40SitePackages/40ImplementYourDesign/Index.md)
33+
34+
### Building Websites
35+
36+
**Content Management**
37+
38+
- [Setup Page Types](../20BuildingWebsites/10ContentManagement/10SetUpPageTypes/Index.md)
39+
- [Create Custom Content Elements](../20BuildingWebsites/10ContentManagement/20CreateCustomContentElements/Index.md)
40+
- [Configure the Backend Layout](../20BuildingWebsites/10ContentManagement/30ConfigureTheBackendLayout/Index.md)
41+
- [Manage Backend User Permissions](../20BuildingWebsites/10ContentManagement/40ManageBackendUserPermissions/Index.md)
42+
43+
**Multilingual Websites**
44+
45+
- [Setup Multiple Languages](../20BuildingWebsites/20MultilingualWebsites/10SetUpMultipleLanguages/Index.md)
46+
- [Translate Content](../20BuildingWebsites/20MultilingualWebsites/20TranslateContent/Index.md)
47+
- [Manage Language Fallbacks](../20BuildingWebsites/20MultilingualWebsites/30ManageLanguageFallbacks/Index.md)
48+
- [Work with Translation Services](../20BuildingWebsites/20MultilingualWebsites/40WorkWithTranslationServices/Index.md)
49+
50+
**Extensions**
51+
52+
- [Find and Install Extensions](../20BuildingWebsites/30Extensions/10FindAndInstallExtensions/Index.md)
53+
- [Configure Common Extensions](../20BuildingWebsites/30Extensions/20ConfigureCommonExtensions/Index.md)
54+
- [Customize Extension Templates](../20BuildingWebsites/30Extensions/30CustomizeExtensionTemplates/Index.md)
55+
- [Troubleshoot Extension Issues](../20BuildingWebsites/30Extensions/40TroubleshootExtensionIssues/Index.md)
56+
57+
**Frontend Development**
58+
59+
- [Understand Fluid Templates](../20BuildingWebsites/40FrontendDevelopment/10UnderstandFluidTemplates/Index.md)
60+
- [Create Responsive Layouts](../20BuildingWebsites/40FrontendDevelopment/20CreateResponsiveLayouts/Index.md)
61+
- [Implement Frontend User Registration](../20BuildingWebsites/40FrontendDevelopment/30ImplementFrontendUserRegistration/Index.md)
62+
- [Add Custom Java Script and CSS](../20BuildingWebsites/40FrontendDevelopment/40AddCustomJavaScriptAndCSS/Index.md)
63+
64+
### Advanced Implementation
65+
66+
**Extension Development**
67+
68+
- [Create a Basic Extension](../30AdvancedImplementation/10ExtensionDevelopment/10CreateABasicExtension/Index.md)
69+
- [Develop with Extbase and Fluid](../30AdvancedImplementation/10ExtensionDevelopment/20DevelopWithExtbaseAndFluid/Index.md)
70+
- [Build Non-Extbase Extensions](../30AdvancedImplementation/10ExtensionDevelopment/30BuildNon-ExtbaseExtensions/Index.md)
71+
- [Create Extension APIs](../30AdvancedImplementation/10ExtensionDevelopment/40CreateExtensionAPIs/Index.md)
72+
73+
**System Integration**
74+
75+
- [Connect to External Services](../30AdvancedImplementation/20SystemIntegration/10ConnectToExternalServices/Index.md)
76+
- [Implement Single Sign-On (SSO)](../30AdvancedImplementation/20SystemIntegration/20ImplementSingleSign-On/Index.md)
77+
- [Setup REST APIs](../30AdvancedImplementation/20SystemIntegration/30SetUpRESTAPIs/Index.md)
78+
- [Integrate with Third-party Systems](../30AdvancedImplementation/20SystemIntegration/40IntegrateWithThird-partySystems/Index.md)
79+
80+
**Performance Optimization**
81+
82+
- [Configure Caching](../30AdvancedImplementation/30PerformanceOptimization/10ConfigureCaching/Index.md)
83+
- [Setup a Content Delivery Network (CDN)](../30AdvancedImplementation/30PerformanceOptimization/20SetUpACDN/Index.md)
84+
- [Database Optimization](../30AdvancedImplementation/30PerformanceOptimization/30DatabaseOptimization/Index.md)
85+
- [Implement Static Site Generation (SSG)](../30AdvancedImplementation/30PerformanceOptimization/40ImplementStaticSiteGeneration/Index.md)
86+
87+
**Deployment and DevOps**
88+
89+
- [Setup CICD Pipelines](../30AdvancedImplementation/40DeploymentAndDevOps/10SetUpCICDPipelines/Index.md)
90+
- [Implement Git Workflows](../30AdvancedImplementation/40DeploymentAndDevOps/20ImplementGitWorkflows/Index.md)
91+
- [Containerization with Docker](../30AdvancedImplementation/40DeploymentAndDevOps/30ContainerizationWithDocker/Index.md)
92+
- [Kubernetes Deployment](../30AdvancedImplementation/40DeploymentAndDevOps/40KubernetesDeployment/Index.md)
93+
94+
### Maintenance and Security
95+
96+
**Regular Maintenance**
97+
98+
- [Backup and Restore Procedures](../40MaintenanceAndSecurity/10RegularMaintenance/10BackupAndRestoreProcedures/Index.md)
99+
- [Update TYPO3 Core](../40MaintenanceAndSecurity/10RegularMaintenance/20UpdateTYPO3Core/Index.md)
100+
- [Update Extensions](../40MaintenanceAndSecurity/10RegularMaintenance/30UpdateExtensions/Index.md)
101+
- [Database Maintenance Tasks](../40MaintenanceAndSecurity/10RegularMaintenance/40DatabaseMaintenanceTasks/Index.md)
102+
103+
**Security**
104+
105+
- [Implmement Security Best Practices](../40MaintenanceAndSecurity/20Security/10ImplementSecurityBestPractices/Index.md)
106+
- [Setup HTTPS](../40MaintenanceAndSecurity/20Security/20SetUpHTTPS/Index.md)
107+
- [Manage User Authentication](../40MaintenanceAndSecurity/20Security/30ManageUserAuthentication/Index.md)
108+
- [Security Incident Response](../40MaintenanceAndSecurity/20Security/40SecurityIncidentResponse/Index.md)
109+
110+
**Monitoring**
111+
112+
- [Setup Application Monitoring](../40MaintenanceAndSecurity/30Monitoring/10SetUpApplicationMonitoring/Index.md)
113+
- [Configure Log Management](../40MaintenanceAndSecurity/30Monitoring/20ConfigureLogManagement/Index.md)
114+
- [Implement Alerts](../40MaintenanceAndSecurity/30Monitoring/30ImplementAlerts/Index.md)
115+
- [Performance Monitoring](../40MaintenanceAndSecurity/30Monitoring/40PerformanceMonitoring/Index.md)
116+
117+
**Troubleshooting**
118+
119+
- [Debug Common Issues](../40MaintenanceAndSecurity/40Troubleshooting/10DebugCommonIssues/Index.md)
120+
- [Use the Admin Panel](../40MaintenanceAndSecurity/40Troubleshooting/20UseTheAdminPanel/Index.md)
121+
- [Work With Exception Logs](../40MaintenanceAndSecurity/40Troubleshooting/30WorkWithExceptionLogs/Index.md)
122+
- [Get Community Support](../40MaintenanceAndSecurity/40Troubleshooting/40GetCommunitySupport/Index.md)

‎Documentation/90Contribute/10Template/Index.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# TYPO3 Step-By-Step Guide Template
2+
3+
*This template includes writing instructions {in curly brackets} and boilerplate text that you can customize with your own text. The [step-by-step Contributor Guide](../20ContributorGuide/Index.md) explains each section in detail, and includes example text for each section. Search the [Guide Registry](../../80GuidesRegistry/Index.md) before you start - your guide might already exist!*
4+
5+
## Title
6+
7+
{Provide a conceptual overview.}
8+
9+
{Feature} enables you to {address pain point}. {Task you are going to learn} helps you {achieve goal}.
10+
11+
## Learning objective
12+
13+
In this step-by-step guide you will {describe what the learner will accomplish}.
14+
15+
## Prerequisites
16+
17+
### Tools and technology
18+
19+
* {Hardware specifications}
20+
* {Software installed}
21+
* {Environments}
22+
23+
### Knowledge and skills
24+
25+
* {Conceptual knowledge}
26+
* {Prior learning}
27+
28+
## Watch the video
29+
30+
{**Optional**. If available, embed the YouTube video version of this tutorial from the TYPO3 official channel.}
31+
32+
Watch this video to follow along with the steps below.
33+
34+
## {Task name}
35+
36+
> **Scope check time**
37+
>
38+
> Don't start writing until you have a clear scope.
39+
>
40+
> If you're unsure about the goal, the audience, or the prerequisites — go back and fix it now. Writing the task section without a solid scope will lead to frustration when you’re deep
41+
> in the details.
42+
43+
{Optional explanatory text}
44+
45+
1. {Write the first step. Start with a verb.}
46+
{Optional: Code sample or screenshot that helps the learner complete this step.}
47+
{Optional: Expected outcome.}
48+
2. {Write the next step. Start with a verb.}
49+
50+
## {Task name}
51+
52+
{Optional explanatory text}
53+
54+
1. {Write the first step. Start with a verb.}
55+
{Optional: Code sample or screenshot that helps the learner complete this step.}
56+
{Optional: Expected outcome.}
57+
2. {Write the next step. Start with a verb.}
58+
59+
## {Task name}
60+
61+
{Optional explanatory text}
62+
63+
1. {Write the first step. Start with a verb.}
64+
{Optional: Code sample or screenshot that helps the learner complete this step.}
65+
{Optional: Expected outcome.}
66+
2. {Write the next step. Start with a verb.}
67+
68+
{For Project guides, use this section to link to existing step-by-step guides}
69+
70+
## Summary
71+
72+
{State the outcome of the step-by-step guide to recap what the learner has achieved.}
73+
74+
Congratulations! You now have {outcome}.
75+
76+
## Next steps
77+
78+
{List links to tasks that the learner could do next.}:
79+
80+
Now that you have {achieved goal}, you might like to:
81+
82+
* Task 1
83+
* Task 2
84+
* Task 3…
85+
86+
## Resources
87+
88+
{**Optional**. List links to related material.}
89+
90+
* Resource 1
91+
* Resource 2
92+
* Resource 3…

‎Documentation/90Contribute/20ContributorGuide/10WhatAreSBSGuides.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# What are step-by-step guides?
2+
3+
TYPO3 step-by-step guides are hands-on tutorials designed to help newcomers **accomplish one practical task**.
4+
5+
Inspired by the [Diátaxis framework](https://diataxis.fr/map/#expectations-and-guidance), which emphasizes distinct content types in technical documentation, step-by-step guides map to the “tutorials” category.
6+
7+
TYPO3 step-by-step guides follow a few key principles:
8+
9+
* **Hands-on learning**: The fastest way to learn is by doing.
10+
* **One clear path**: No branches \- just one method that works, from start to finish.
11+
* **Minimal explanation**: Explain only what’s necessary to keep someone moving. Link out for deeper context.
12+
* **A successful finish**: Every step produces visible progress, and the outcome is reliable and repeatable.
13+
* **Aligned with TYPO3’s official documentation**: linking out to deeper material as needed
14+
* Takes **less than 30 minutes** to complete
15+
16+
> A good step-by-step guide follows the [single-responsibility principle (SRP)](https://en.wikipedia.org/wiki/Single-responsibility_principle): **it should do one thing, and do it well.** > Every step contributes directly to a single learning objective, and nothing more.
17+
>
18+
> If you find yourself adding “If…” or “Alternatively…”, the guide may violate the single-responsibility principle.
19+
20+
## What are they not?
21+
22+
Step-by-step guides aren’t examples. Examples are usually found in the documentation, and help to illustrate concepts - they are meant to be studied and understood. Guides, in contrast, take the reader through a path of sequential steps, and are designed to be actively followed to learn a new concept.
23+
24+
## Modular by design
25+
26+
Step-by-step guides are modular. Each guide is an atomic unit of action — small, focused, and self-contained, with one learning objective and one clear outcome. Guides can be combined to form larger tutorials or workshops, or used independently for self-led learning.
27+
28+
## How do step-by-step guides fit in the existing TYPO3 documentation ecosystem?
29+
30+
| TYPO3 documentation | Step-by-step guide |
31+
| :---- | :---- |
32+
| **Information oriented** Supports exploration and problem-solving for people seeking answers or understanding.. | **Learning oriented** Helps people learn through hands-on experience. |
33+
| **Comprehensive** Presents various approaches, configurations, and possibilities. Also covers edge cases. | **Single clear path** Follows a carefully managed path from start to finish with guaranteed success. |
34+
| **Blends doing and explaining** Combines how-to instructions, explanations, and reference information. | **Focused on doing** Prioritizes action with minimal explanation; links out to deeper material in the docs. |

‎Documentation/90Contribute/20ContributorGuide/20WhatAreProjectGuides.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# What are project guides?
2+
3+
A project guide is made up of multiple step-by-step guides.
4+
5+
Project guides help learners complete multi-part processes by combining individual tasks into a coherent whole. They provide a clear learning sequence and maintain a narrative that shows how the parts fit together.
6+
7+
## How project guides extend step-by-step guides
8+
9+
Project guides compose several atomic step-by-step guides into a larger or more advanced outcome.
10+
11+
Use a project guide when:
12+
13+
* Multiple distinct tasks are required
14+
* Some tasks are already covered in other guides
15+
* It would take more than 30 minutes or feel overwhelming as one block
16+
17+
**Examples**
18+
19+
* Build a multilingual site
20+
* Develop a custom frontend plugin with user authentication
21+
22+
## Project guides are modular
23+
24+
Project guides follow the same template as regular step-by-step guides, the only difference is that the Task section looks a bit different.
25+
26+
Project guides are **fully modular**. They are made entirely by linking out to existing step-by-step guides, like ingredients in a recipe.
27+
28+
You should only create a project guide once all the step-by-step guides it depends on have been created. This helps avoid incomplete or blocked project guides.
29+
30+
*Exception*: In rare cases, an author may find that some procedural steps don’t justify a standalone guide — perhaps because they’re too minor, too specific, or only make sense in the context of the larger flow. In these situations, it may be appropriate to include a small number of inline steps within a project guide. Use this approach only when a task truly cannot stand alone.

0 commit comments

Comments
 (0)