[Bug 2072346] [NEW] Separate task, reference, and conceptual content

[Jay Faulkner]

Public bug reported:

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

Many of the Ironic documentation pages contain a mix of instruction
("how-to" docs or procedures), reference information, and conceptual
information. Rewrite each page to contain (primarily) only one type of
information. Especially, write tasks as clear, step-by-step procedures.

Pages will need to be separated, moved, and in some cases merged. This
won't be a fast process; I recommend that you keep this backlog issue
open and track the changes in it as you go. The tasks in the following
section, [Rewrite page headings](#rewrite-page-headings) complement this
work and will need to be tracked similarly.

The following table lists a few arbitrarily selected pages, suggests new
page titles, and where necessary suggests how to reorganize the page.

| Page | Suggested new name | Information type | Suggested reorganization |
| ---- | ------------------ | ---------------- | ------------------------ |
| [Troubleshooting][ex2] | Using Ironic maintenance mode | Task | |
| [Configuration][ex3] | Configuring Ironic for standalone | Task | Move "Using CLI" to its own page |
| [Enrollment][ex4] | Enrolling a node in Ironic | Task | |
| [Bare Metal Service Upgrade Guide][ex5] | Ironic Upgrade Guide | Task | Split into a linked series of pages |
| [Intel IPMI Driver][ex6] | no change | Reference | None. The [Drivers, Hardware Types and Interfaces][ex7] section is Reference information. |
| [Enabling Notifications][ex8] | "Notification Reference for ironic". Make the table of contents title ("Enabling Notifications") agree with the page title. | Reference | Separate the reference from the enablement instructions and put on two separate pages |

[ex1]: https://docs.openstack.org/ironic/latest/install/advanced.html
[ex2]: https://docs.openstack.org/ironic/latest/install/troubleshooting.html#
[ex3]: https://docs.openstack.org/ironic/latest/install/standalone/configure.html
[ex4]: https://docs.openstack.org/ironic/latest/install/standalone/enrollment.html
[ex5]: https://docs.openstack.org/ironic/latest/admin/upgrade-guide.html
[ex6]: https://docs.openstack.org/ironic/latest/admin/drivers/intel-ipmi.html
[ex7]: https://docs.openstack.org/ironic/latest/admin/drivers.html#
[ex8]: https://docs.openstack.org/ironic/latest/admin/notifications.html

** Affects: ironic (Ubuntu)
     Importance: Undecided
         Status: Invalid


** Tags: docs-audit-2024 documentation

** Changed in: ironic (Ubuntu)
       Status: New => Invalid

-- 
You received this bug notification because you are a member of Ubuntu
OpenStack, which is subscribed to ironic in Ubuntu.
https://bugs.launchpad.net/bugs/2072346

Title:
  Separate task, reference, and conceptual content

Status in ironic package in Ubuntu:
  Invalid

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

  Many of the Ironic documentation pages contain a mix of instruction
  ("how-to" docs or procedures), reference information, and conceptual
  information. Rewrite each page to contain (primarily) only one type of
  information. Especially, write tasks as clear, step-by-step
  procedures.

  Pages will need to be separated, moved, and in some cases merged. This
  won't be a fast process; I recommend that you keep this backlog issue
  open and track the changes in it as you go. The tasks in the following
  section, [Rewrite page headings](#rewrite-page-headings) complement
  this work and will need to be tracked similarly.

  The following table lists a few arbitrarily selected pages, suggests
  new page titles, and where necessary suggests how to reorganize the
  page.

  | Page | Suggested new name | Information type | Suggested reorganization |
  | ---- | ------------------ | ---------------- | ------------------------ |
  | [Troubleshooting][ex2] | Using Ironic maintenance mode | Task | |
  | [Configuration][ex3] | Configuring Ironic for standalone | Task | Move "Using CLI" to its own page |
  | [Enrollment][ex4] | Enrolling a node in Ironic | Task | |
  | [Bare Metal Service Upgrade Guide][ex5] | Ironic Upgrade Guide | Task | Split into a linked series of pages |
  | [Intel IPMI Driver][ex6] | no change | Reference | None. The [Drivers, Hardware Types and Interfaces][ex7] section is Reference information. |
  | [Enabling Notifications][ex8] | "Notification Reference for ironic". Make the table of contents title ("Enabling Notifications") agree with the page title. | Reference | Separate the reference from the enablement instructions and put on two separate pages |

  [ex1]: https://docs.openstack.org/ironic/latest/install/advanced.html
  [ex2]: https://docs.openstack.org/ironic/latest/install/troubleshooting.html#
  [ex3]: https://docs.openstack.org/ironic/latest/install/standalone/configure.html
  [ex4]: https://docs.openstack.org/ironic/latest/install/standalone/enrollment.html
  [ex5]: https://docs.openstack.org/ironic/latest/admin/upgrade-guide.html
  [ex6]: https://docs.openstack.org/ironic/latest/admin/drivers/intel-ipmi.html
  [ex7]: https://docs.openstack.org/ironic/latest/admin/drivers.html#
  [ex8]: https://docs.openstack.org/ironic/latest/admin/notifications.html

To manage notifications about this bug go to:
https://bugs.launchpad.net/ubuntu/+source/ironic/+bug/2072346/+subscriptions