Convert Guides in the Documentation to Step-by-Step Guides

What is this guide about?

TL;DR: This guide helps to create new step-by-step guides from existing how-to guides in the documentation.

TYPO3 step-by-step guides help beginners and advanced users quickly learn how to perform tasks they aren’t familiar with. (If you haven’t contributed a step-by-step guide yet, see the TYPO3 Step-by-Step Contributor Guide for more information.)

When adding new content to an existing body of knowledge, overlaps are unavoidable. Before the step-by-step guides were introduced, the TYPO3 documentation already had several guides available via the “All documentation” menu on the documentation home page:

• Getting Started Tutorial
• Site Package Tutorial
• Administration (Install, Update)
• Extension Development
• Frontend Localization Guide
• Editors Guide

These guides contain actionable (how-to) content, as well as explanations of TYPO3 features (tools, UIs, and more). We want to turn the actionable parts into the step-by-step guide format to achieve these benefits:

1. The guides will have a standardized format that provides consistency and helps learners focus on the tasks.
2. The guides can be integrated into learning paths that consist of a series of step-by-step guides targeted towards specific audiences. Learning paths help beginners to achieve bigger goals by addressing a series of smaller goals.

In this guide, you’ll learn the steps for gently transforming an existing guide into one or more step-by-step guides.

Guide migration workflow

Transferring existing guides over to the new step-by-step guide structures—both the internal and external structure—involves four steps:

1. Review an existing guide to see if and where it fits
2. Create one or more step-by-step guides in the guide structure
3. Write the guide(s)
4. Remove the legacy content from the documentation and link to the new step-by-step guide

Meet the Guide Conversion Map

The list of existing guides at the beginning of this document looks small (just six items), but each contains numerous documents to process. The Warning: Uninitialized string offset 0 in /opt/guides/vendor/phpdocumentor/guides/src/ReferenceResolvers/DocumentNameResolver.php on line 60 is an interactive spreadsheet that helps to organize the documents and keep track of the conversion process.

Here is a screenshot of the map:

![Screenshot of map spreadsheet][Documentation/90Contribute/20ContributorGuide/Images/MapScreenshot.png]

Getting familiar with someone else's spreadsheet can be challenging. The following information helps you to get a smooth start.

The far-left column shows the top-level guide. The third column (“Guide Title”) lists individual subpages of each guide hierarchically (note the indenting).

These two columns are your starting point. For each guide, you will gradually fill the rest of the columns with information that helps you or another contributor convert the guide into one or more step-by-step guides.

How to review and categorize an existing guide

When you start working with the map, you will see some rows already filled. Search for rows with these settings:

• Status: “-”
• Action: “-”

These rows contain possible candidates for conversion.

Now, go through these rows and look at the “Guide Title” column to find a title that you’re familiar with, you want to have converted, or that otherwise looks like a good candidate.

As an example, we’ll pick “Creating a site package”:

![Screenshot of selecting a row to work on][Documentation/90Contribute/20ContributorGuide/Images/MapChooseCandidateRow.png]

Click the link to open the original document.

Read through it to determine:

• if it is actionable
• how many goals or variants of a task it includes

In this example, the guide is actionable and lists two ways of achieving the intended result: Manual creation and using the Site Package Builder. For the manual creation process, it links to another guide (the TYPO3 site package tutorial), so it effectively contains a single goal and one way of achieving it. Good!

Now, take a look at the step-by-step guide repository and verify if the topic is already covered. Then go ahead and update the map:

1. Select a Category: “Site packages” would be a natural fit. If you cannot seem to find an appropriate category, see the TYPO3 Step-by-Step How to Place Guides in the Structure guide that contains detailed instructions and tips for optimal categorization.
2. Set the Status to “Not started”.
3. Set the Action to “Convert”.
4. Set the Number of Goals to 1.

The rest of the columns are optional for the beginning; Fill them if you have the information at hand or leave them for later. The Column reference section below describes all columns you can fill.

Now, the row should look like this:

![Screenshot of completed row][Documentation/90Contribute/20ContributorGuide/Images/MapFilledOutRow.png]

Such a filled-out column sets the informational basis for writing a step-by-step guide. Anyone who picks up the tasks to write that guide can start with a good amount of information to write the guide, add it to learning paths or SkillDisplay skills, and more.

Next steps in the guide creation process

Column reference {#column-reference}