TYPO3 Quickstart: Resolving Duplicate Tabs In Docs

In this article, we'll delve into the issue of duplicate tabs within the TYPO3 quickstart documentation, specifically focusing on the Composer and "ddev typo3 setup" tabs. This redundancy can be confusing for users, especially those new to TYPO3 and ddev. We will explore the root cause of this duplication, trace its history through various pull requests, and outline a clear solution to streamline the quickstart guide.

Understanding the Problem of Duplicate Tabs

The TYPO3 quickstart guide, located in docs/content/users/quickstart.md, currently features three tabs designed to help users set up their TYPO3 projects. However, a closer examination reveals that the first tab, labeled "Composer," and the third tab, titled "ddev typo3 setup," are nearly identical. This duplication presents a significant problem because it offers no meaningful distinction to users, potentially leading to confusion and a less efficient setup process. Identifying and rectifying such redundancies is crucial for maintaining clear and user-friendly documentation.

Current Tab Structure and Its Shortcomings

To better understand the issue, let's break down the current tab structure:

1. Composer: This tab guides users through creating a new TYPO3 project using Composer and subsequently running the ddev typo3 setup CLI command. This approach automates much of the initial setup process, making it convenient for new projects.
2. Git Clone: This tab caters to users who prefer to work with existing repositories. It involves cloning a repository and manually using the web installer for setup. This method is suitable for those migrating existing projects or contributing to established TYPO3 sites.
3. ddev typo3 setup: This tab, intended to offer an alternative setup method, mirrors the functionality of the "Composer" tab. It also creates a new project via Composer and runs the ddev typo3 setup CLI. This overlap is the core issue we aim to address.

Minimal Differences, Maximum Confusion

The critical problem lies in the minimal differences between the "Composer" and "ddev typo3 setup" tabs. While there are slight variations in the commands provided—such as the inclusion of quotes around the project name in one tab (ddev composer create-project "typo3/cms-base-distribution") and the project name (--project-name="My TYPO3 site" vs. --project-name="demo TYPO3 site")—these distinctions are primarily cosmetic. They do not warrant a separate tab, as they do not represent fundamentally different approaches to project setup. This redundancy can mislead users into thinking there are significant differences, leading to unnecessary decision-making and potential errors.

Tracing the History: How Duplication Occurred

To fully grasp the problem, it's essential to trace the history of these tabs and understand how the duplication arose. The current situation is a result of unintentional changes introduced through a series of pull requests. By examining these changes, we can pinpoint the exact steps that led to the redundancy and ensure that our solution effectively addresses the root cause.

The Origin: PR #7230

The story begins with PR #7230, which aimed to create a comprehensive TYPO3 quickstart guide with three distinct approaches. Initially, these approaches were genuinely different, catering to various user preferences and scenarios. The three original approaches were:

1. Composer + ddev typo3 setup: This method provided an automated CLI setup, streamlining the process for users starting new projects.
2. Git Clone + manual web installer: As mentioned earlier, this option was designed for users working with existing repositories, offering a manual setup route.
3. Composer + touch public/FIRST_INSTALL + ddev typo3 setup: This approach combined Composer with a manual FIRST_INSTALL file creation, followed by the automated CLI setup. It was intended as a variation of the first method, offering a slightly different setup flow.

At this stage, the three tabs represented distinct pathways, each serving a specific purpose. However, subsequent changes would alter this landscape.

The Turning Point: PR #7302

The pivotal moment came with PR #7302, which refactored the first "Composer" tab. This refactoring, while intended to improve the tab, inadvertently eliminated the distinction between the first and third tabs. The key change was shifting the first tab from using touch public/FIRST_INSTALL followed by the manual web installer to utilizing the ddev typo3 setup CLI command. This shift aligned the first tab's functionality almost entirely with the third tab. The refactoring effectively made the first tab a duplicate of the third, undoing the initial diversity of approaches.

The Lost Distinction

With the first tab now employing the same ddev typo3 setup CLI command as the third, the cosmetic differences—such as the presence or absence of quotes and slight variations in project names—became the only differentiating factors. These minor differences were insufficient to justify maintaining separate tabs, leading to the current redundancy.

Proposed Solution: Streamlining the Quickstart Guide

Given the history and the current state of the TYPO3 quickstart documentation, the solution is clear: remove the redundant "ddev typo3 setup" tab. This action will streamline the guide, reduce user confusion, and align the TYPO3 quickstart with the structure used by most other CMS quickstarts in the same document. A streamlined guide improves usability and ensures that users can quickly find the information they need.

A Two-Tab Structure: Clarity and Efficiency

The proposed solution entails consolidating the quickstart guide into a two-tab structure:

1. Composer: This tab will focus on setting up new projects using Composer and the automated ddev typo3 setup command. It will serve as the primary method for users starting fresh TYPO3 installations.
2. Git Clone: This tab will continue to guide users through the process of working with existing projects, utilizing the manual web installer for setup. It will remain the go-to option for those contributing to or migrating existing TYPO3 sites.

Aligning with Best Practices

This two-tab structure aligns with the best practices observed in other CMS quickstarts. By offering clear, distinct options for new and existing projects, the guide becomes more intuitive and user-friendly. This simplification reduces the cognitive load on users and allows them to focus on the core tasks of setting up their TYPO3 projects.

Practical Implications and Benefits

The removal of the duplicate tab has several practical implications and benefits for both users and maintainers of the documentation.

Enhanced User Experience

For users, the streamlined guide means a clearer and more efficient setup process. With only two distinct options, users can quickly identify the method that best suits their needs without having to sift through redundant information. This improved user experience can lead to higher satisfaction and a smoother onboarding process for new TYPO3 developers.

Simplified Maintenance

For maintainers, a streamlined guide is easier to maintain and update. Reducing redundancy minimizes the risk of inconsistencies and ensures that updates are applied uniformly across the documentation. This simplification translates to reduced maintenance overhead and a more reliable quickstart guide.

Consistency with Other CMS Guides

By aligning the TYPO3 quickstart with the structure of other CMS guides, we create a more consistent user experience across the ddev ecosystem. This consistency makes it easier for users familiar with other CMS setups to quickly grasp the TYPO3 setup process. Consistency is a key principle in user interface design, and its application here enhances the overall usability of the documentation.

Conclusion

The presence of duplicate tabs in the TYPO3 quickstart documentation was an unintended consequence of a series of refactoring efforts. While each individual change aimed to improve the guide, the cumulative effect was the creation of redundancy. By understanding the history of these changes and their impact, we can implement a targeted solution: removing the duplicate "ddev typo3 setup" tab. This streamlined approach not only enhances the user experience but also simplifies maintenance and aligns the TYPO3 quickstart with best practices in documentation design. The proposed two-tab structure offers a clear and efficient pathway for users to set up their TYPO3 projects, whether they are starting fresh or working with existing repositories.

For further information and resources on TYPO3 and ddev, you can visit the official TYPO3 website and the ddev documentation.