User guide needs updating

[aeva black]

There are a few problems with the user guide right now:
  http://git.openstack.org/cgit/openstack/ironic/tree/doc/source/deploy/user-guide.rst

Cosmetically, is not formatted properly for RST. Lines are too long and some have extra non-printing characters.

The diagrams are also misleading, if not incorrect.

http://docs.openstack.org/developer/ironic/_images/deployment_architecture_1.png
Figure 1.3.1 "Deployment Architecture" places ir-cond on the same host as n-cpu, which is not advisable in some situations. It should be made clear that a security-conscious operator should place ir-cond on an isolated host, as it is the *only* service which requires access to both data plane and IPMI control plane. This same diagram suggests placing ir-api on a monolithic "Cloud Controller Node", but does not explain why this unusual choice was made. Lastly, it does not include any depiction of the physical servers which Ironic is going to manage, nor the IPMI network connectivity to them which is required.

http://docs.openstack.org/developer/ironic/_images/deployment_steps.png
Figure 1.3.3 "Bare Metal Deployment Steps" looks like an adaptation of an old diagram of mine, but it is now significantly factually incorrect.

http://docs.openstack.org/developer/ironic/deploy/user-guide.html#deploy-process
The "Deploy Process" section describes fetching the deploy kernel & ramdisk from the nova flavor; this was done in Icehouse, but is no longer recommended in Juno. There are several references to a "bare metal database" which is misleading, if not incorrect.

Additionally, much of this is overly specific to the pxe_ipmitool driver, which will not be the only driver in the Juno release.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/116168

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/116168
Committed: https://git.openstack.org/cgit/openstack/ironic/commit/?id=daaad27b75be661b41f494e12f11e1ffbcb26c26
Submitter: Jenkins
Branch: master

commit daaad27b75be661b41f494e12f11e1ffbcb26c26
Author: Ruby Loo <email address hidden>
Date: Fri Aug 22 03:22:00 2014 +0000

    properly format user guide in RST

    The user guide isn't formatted properly for RST. Cosmetically,
    the lines are too long and some have extra non-printing characters.
    Lists aren't formatted for RST.

    This fixes the file so that the lines are no more than 80 characters
    wide, removes the non-printing characters, and makes use of
    RST-formatting for the lists.

    The text itself is not modified.

    Change-Id: I8d2f3e4723e619014c056946e4f226d9c0e8f48a
    Partial-Bug: #1353688

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/136136

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/136136
Committed: https://git.openstack.org/cgit/openstack/ironic/commit/?id=12c83984b682a957baeed782e26edd8f07965e30
Submitter: Jenkins
Branch: master

commit 12c83984b682a957baeed782e26edd8f07965e30
Author: Ruby Loo <email address hidden>
Date: Thu Nov 20 21:33:33 2014 +0000

    Update 'Introduction to Ironic' document

    The first few sections of the 'Introduction to Ironic' document were updated to:
    - mention that it is included with OpenStack releases starting with Kilo
    - mention that Swift is missing from the Conceptual Architecture diagram
    - removes Figure 1.3.1 "Deployment Architecture" and the text surrounding
      that for several reasons: it places ir-cond on the same host as n-cpu, which
      is not advisable in some situations; it suggests placing ir-api on a
      monolithic "Cloud Controller Node", but does not explain why this unusual
      choice was made; and it does not include any depiction of the physical
      servers which Ironic is going to manage, nor the IPMI network connectivity
      to them which is required.
    - mentions that for security reasons, ir-cond should be placed on an isolated
      host, as it is the *only* service which requires access to both data plane
      and IPMI control plane.
    - modified (what was Figure 1.3.2) deployment_architecture_2.png so that it
      doesn't include a figure number

    Change-Id: Ifeeba636c9e7de65385e9f9c631709b2dd09e25b
    Partial-Bug: #1353688

[Ruby Loo (rloo)]

I cleaned up some of the documentation, but did not address the issues mentioned in the bug, related to:
- http://docs.openstack.org/developer/ironic/_images/deployment_steps.png
- http://docs.openstack.org/developer/ironic/deploy/user-guide.html#deploy-process

[Jim Rollenhagen (jim-rollenhagen)]

What's left to do here? I don't like these open-ended bugs.

[Julia Kreger (juliaashleykreger)]

The current state of the user guide appears to have had the remaining highlighted issues corrected. https://docs.openstack.org/ironic/latest/user/index.html I'm going to mark this issue as complete.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/516190

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/516190
Committed: https://git.openstack.org/cgit/openstack/ironic/commit/?id=4f726f356adc58f80140b88ae64b9f9d8cd9d025
Submitter: Zuul
Branch: master

commit 4f726f356adc58f80140b88ae64b9f9d8cd9d025
Author: chenxing <email address hidden>
Date: Mon Oct 30 14:26:24 2017 +0800

    Fix the format issues of User guide

    Change-Id: Ic4cf6d9f57ab612d3b4220ef3d6ad9365093df51
    Closes-Bug: #1353688

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/ironic 9.2.0 release.