Authoring Guide Pages Using Documentation Tools

A guide page focuses on a single topic, providing links to functions that share functionality. Sections are provided to link to other related documents.
The material below assumes that you have already set up an appropriate paclet directory structure for saving and working with documentation using Documentation Tools. To learn more about creating paclets, consult the Creating Paclets tutorial.
Below, a paclet called Example will be used, with PublisherID JohnDoe.
Setting Up DocumentationTools
Choose Palettes Documentation Tools from the system menu bar. A palette will appear on the right side of the screen. Select the G tab at the top of the palette for guide page authoring tools.

When authoring paclet documentation for the first time with Documentation Tools, the paclet location will need to be configured. Click Add Paclet ... near the palette's top and navigate to and choose the top directory of your paclet. This will activate the links in the authoring notebooks for testing purposes.
If you have not already created a paclet documentation directory structure, then when a new paclet is added, Documentation Tools will automatically create the directory Paclet Name > Documentation > Language and the directories Guides, ReferencePages and Tutorials inside the Language directory. Additionally, the Symbols directory will be created inside the ReferencePages directory. By default, Language will be the English name for your chosen Wolfram System language and will typically match $Language.
Clicking New Guide Page brings up a dialog requesting that the title of the new guide be specified.

Once that is done, clicking OK will construct a new guide page with the title and metadata already filled in. In addition, the guide page will be saved in the paclet's Guides directory.

Note: The authoring notebooks contain a series of placeholders that will not be included with the build unless you explicitly edit them. These placeholders will typically contain four X's.

Note: A sample guide page can be found by clicking ? near the top of the Documentation Tools palette.

Enter some descriptive text describing what the guide covers.

Add links and descriptions for emphasized functions by using the 1 Line Function Listing button near the top of the Documentation Tools palette. Place the cursor in the part of the cell where the four X's are to the left of description and replace the X's with the function name. Add a short description to the right, typing over description.

Click 1 Line Function Listing to automatically create a link.

Less important functions may be listed as function inline listings.

Type a function name in place of the X's. Use the button to add more.

With the cursor in the cell or at the cell bracket, click Functions Inline Listing. If you later want to add more functions to the list, select the cell bracket and click Functions Inline Listing. The function list will again be plain text. Add more function names and then click Functions Inline Listing again.

Related functions can be organized into groups by placing the cursor between cells and clicking Delimiter on the DocumentationTools palette.
Adding Cross-Links
The Tech Notes section is for related tech notes, the More About section is for links to guide pages, and the Related Links section is for other related pages (including webpages).

Start typing in any section to add text. Then make a selection.

Choose Links on the Documentation Tools palette and pick the type of link from the column. (Expand More Link Tools for more options.)

Clicking Link to Tech Note makes a tech note link.

Adding Search Index Information
Scroll to the bottom of the authoring notebook and expand the Keywords cell group.

"Keyword" cells are what the Mathematica search index uses when cataloging the authoring notebooks and are not case sensitive.
Keywords are set up to return the page in the list of search results if a user were to search for that word in Wolfram Documentation.

Leaving Four X's
Whenever a cell is left with the content four X's, it will be omitted by the build process. Thus the author need not do anything with such cells.
Preview Button
At the top of the authoring notebook is a Preview button.

Clicking the Preview button generates a built version of the authoring notebook.