Improve instructional documentation

Bug #2072356 reported by Jay Faulkner
8
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Ironic
Triaged
Low
Unassigned

Bug Description

This issue was an action item from the Ironic documentation audit.

Rewrite tasks as step-by-step procedures. Following is an outline template (expanded from the [implementation plan](./ironic-implementation.md) and a set of formatted examples created from the Ironic [BIOS Configuration](https://docs.openstack.org/ironic/latest/admin/bios.html) page.

### Outline

Title (using "-ing" verb, e.g. "Installing a driver")
- Prerequisites (What needs to exist or happen first.) Can include:
    - References to other procedures
    - External links (to dependencies, for example)
- Procedure
  1. Step 1 (Describe how to perform the step, possibly with an example; for example: "Run the install script: `$ appinstall --default`")
  2. Step 2 (and so on)
- Result (optional -- include if the result of the procedure is unexpected or exceptional)
- Postreq (Anything that needs to be done after the procedure, for example cleanup. Can include links to the next task in a larger procedure, or a set of choices about what to do next.)

### Example task

The existing page [Install and configure the Bare Metal service](https://docs.openstack.org/ironic/2024.1/install/install.html) is an instructional page with many of these recommendations already in place. Its main drawback is that it's monolithic – it's long, complicated, and difficult to follow. Break procedures like this into several pages, analogous to how you'd break up a long function using subroutine calls.

Below is an outline of a modified version of the process, broken into several pages, along with an explanation for the changes.

Installing the Bare Metal service (_page title: conform to [task heading recommendations](#rewrite-page-headings)_)
- Prerequisites (_shortened from "Install and configure prerequisites"_)
    - Set up the database for Bare Metal (_link to a procedure on a separate page for the database setup_)
    - Create a configuration file (_rather than interrupt the procedure with this, have the user do it as a preparation step. Again, link to a separate page that explains how. Instructions for individual config settings can be in-line, as in the current procedure._)
- Procedure (_steps required for the installation_)
    - Step 1. Install the ironic components (_the current approach is to provide three choices, one for each Linux package manager. This seems simpler than providing a separate procedure for each flavor of Linux, assuming the package management choices are the only difference._)
    - Step 2. Configure the ironic-api service (_This step is long enough that it should be a link to another standalone page, containing all five steps in this section. For steps 1, 2 and 3, showing the file contents is not sufficient: explicitly instruct the user to modify the config file they created in the Prerequisites. And add "Configuring ironic-api behind mod_wsgi" as a separate procedure on its own page, linked from the "Configure the ironic-api service" page_)
  - Step 3. Configuring the ironic-conductor service (_again, this is a long sub-procedure, so put it on a separate page and link to it_)
- Postreqs (_add this section if there's anything that needs to be done afterward that's not part of the installation. For example, restarting a monitoring process or that sort of thing. Also, tell the user what their main options are for next steps, with links to those pages._)

Make "Configuring single-process ironic" a separate page that cleanly explains the procedure, and list it as an option up front – not after they've read the entire install procedure.

Changed in ironic:
status: New → Triaged
importance: Undecided → Low
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.