Improve instructional documentation
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](.
### 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:/
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
- 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 |