Creating new guides | RHACM doc process

Follow these instructions if you have to set up a new guide or need to rename them.

Prerequisites

You must have access to the following tools and directories:

GitHub
The stolostron repository
Red Hat VPN
Pantheon
GitLab

Important: Do you really need a new guide? See the documentation architect to discuss placement of new content.

To create a new guide in the product documentation, you must create a new folder in your repository, and a new book in Pantheon. When you create a new folder, you must also create a main.adoc, a master.adoc symlink to the main.adoc file, and docinfo.xml file in your new folder. See the repository for examples.

Creating a new folder

Option A: From GitHub

Log in to GitHub and navigate to the stolostron/rhacm-doc repository.
Click the Add file button > Create new file.
When you enter the name of the folder, select the forward slash (/) to continue adding a file to your folder.
Add the main.adoc file for your folder. The contents of your file might resemble the following file:
```
include::modules/common-attributes.adoc[]

= Book/guide name

include::intro.adoc[leveloffset=+1]
include::guide_task1.adoc[leveloffset=+2]
include::guide_task2.adoc[leveloffset=+2]
```
Important: The “Book/guide name” must match the name of the book in Pantheon. If not, the build will fail.

Add the docinfo.xml file to your new folder. Your docinfo.xml file might resemble the following information:

<productname>{product-title}</productname>
<productnumber>{product-version}</productnumber>
<subtitle>Manage cluster</subtitle>
<abstract>
    <para>Manage cluster in {product-title}</para>
</abstract>
<authorgroup>
    <orgname>{product-title} Team</orgname>
</authorgroup>
<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

Option B: From your text editor

(VS Code or Atom is recommended to preview, prevent errors, and work in collaboration with dev.)

Verify that you are in the rhacm-docs repository by running the following command from your terminal:
```
pwd
```
Your path might resemble the following content:
```
/Users/local-cpu-name/rhacm-docs
```
If you are using Visual Studio Code (VSC), select the New Folder icon to create a folder.

Add a symlink to the modules folder

You must add a symlink to the modules folder in your new folder to resolve the conrefs. You can copy a file from another folder in the editor, or see the following steps (Mac only):

Open a terminal and navigate to the new GitHub folder.
Enter the following command:
```
ln -s ../modules modules
```
Commit the change to your Git repository.

Add a symlink to reference the `main.adoc` file from the `master.adoc` file

This moves us toward minimizing non-inclusive language. You must add a symlink to reference the main.adoc file so the master.adoc becomes a passthrough. Complete the following steps (Mac only):

Open a terminal and navigate to the new GitHub folder.
Enter the following command:
```
ln -s main.adoc master.adoc
```
If there is already a master file, you will see an error that it already exists. Copy the content of the master file into your main file and delete the existing master file.
Commit the change to your Git repository.

Set up a new book in Pantheon

You must complete the Set up new title form to create a new book. Log in to Pantheon and select the Set up a new title button.

Complete the following steps to complete the New title form:

Verify if you are setting up a new folder from an existing repository in GitLab by selecting one of the options that is provided. If you are creating a new book in a set of books that is already building correctly, select the option for an already set up environment.
If the repository exists in GitLab, values for the product title and version number are complete.
From the GitLab Group section click the drop-down button and select Documentation - Red Hat OpenShift Enterprise.
For GitLab Project, select Red Hat Advanced Cluster Management for Kubernetes.
Select 1.0 for the preview branch. This one is not used, but requires a value.
For the Stage Branch, select the release number for your book. For example, select 2.1.
Enter information for the Content Title, which is your book title. Example: Install.
Select Book for the Content Type.
Ensure that the checkbox for Use default content directory is selected, also select AsciiDoc as the Content Markup.
You can add multiple new titles by selecting the Add additional title button. Otherwise, select Submit when the form is complete.
Run a manual build to pick up the new book. For more information, see Build and publish.

Troubleshooting steps for the `no main file` error message after building the new book:

No “Title URL fragment”

In the Pantheon interface, select the edit (pencil) icon beside your new book. It appears when you hover over the book title.
Verify that there is also a Title URL fragment listed in the field. It is generally an all lowercase version of the Title name that is listed.
If it is not there, add it.
If that doesn’t resolve the error with your next build, try deleting and recreating the symlink in the folder of the new book.

Default content directory not working

In the Pantheon interface, select the down arrow beside the staging build for your book and select “Edit configuration.”
Clear the box for “Use default content directory”.
Manually enter the directory name for your book. Note: I think this might only be an issue with book titles with multiple words in it, though I have not confirmed that.

Renaming

Only rename a folder/guide when absolutely needed as a result of product change. Be sure to alert the team in a Slack message so they don’t create links to the folder you are renaming.

Rename the folder in the source, as Git directory must match the URL. (Git remains the source of truth.)
Rename the guide in the docinfo.xml file.
Rename the title of the master.adoc.
Using find/replace, change all links that are impacted.
Log in to Pantheon.
Click Edit title.
Change the name and the URL fragment. The URL fragment is automatically created as you type your name. Use this value, as the build seems to depend on that later. Keep URL fragment in lowercase.
Click Rename to save.
Select the drop-down error for the book and click Edit Configuration.
Update the Content Directory field with the new name of the folder.
When links and files/folders are all changed, as well as titles, run a build.