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 Bugs, which is subscribed to Ubuntu. https://bugs.launchpad.net/bugs/2072346 Title: Separate task, reference, and conceptual content To manage notifications about this bug go to: https://bugs.launchpad.net/ubuntu/+source/ironic/+bug/2072346/+subscriptions -- ubuntu-bugs mailing list ubuntu-bugs@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs