Separate task, reference, and conceptual content
Affects | Status | Importance | Assigned to | Milestone | |
---|---|---|---|---|---|
Ironic |
Triaged
|
Low
|
Unassigned |
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]
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 |
| ---- | ------------------ | ---------------- | -------
| [Troubleshootin
| [Configuration]
| [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:/
[ex2]: https:/
[ex3]: https:/
[ex4]: https:/
[ex5]: https:/
[ex6]: https:/
[ex7]: https:/
[ex8]: https:/
Changed in ironic: | |
status: | New → Triaged |
importance: | Undecided → Low |