docs: pre install guide quick install is visually un-readable

[Andrew Woodward]

docs: fuel-docs/pages/pre-install-guide/0060-quick-install-fuel.rst
http://docs.mirantis.com/fuel/fuel-4.1/pre-install-guide.html#configuring-fuel-using-the-iso-image

The text between the images makes no sense
The text and images show no structure
There appears to be no purpose or goal
The images have no visual breaking between each other and the text related to each image
The images are not scaled to the size of the page (might not be fixable)

[Mike Scherbakov (mihgen)]

If we still want to fix this in 5.0, please increase priority to high.

[Meg McRoberts (dreidellhasa)]

This is being implemented as part of the restructuring of the docs -- the User's Guide is "how to deploy Mirantis OpenStack using Fuel". It will begin with a summary table of steps to take, each of which will link to a section in the doc that has one of these screen shots (as appropriate) with brief information about how to complete the screen and links to other places in the docs that have more information. Along the way, I'll clean up the mechanics of these screen shots and I think the commentary for each screen will improve the aesthetics.

[Mike Scherbakov (mihgen)]

Is it done or still in progress?

[Meg McRoberts (dreidellhasa)]

Define "done" ;-) Seriously, this is happening as part of the new User's
Guide.
We have new screen shots with headers and commentary between them,
which solves this problem, but I have a bit more work to do before the guide
is ready for review. So I guess this is "In Progress" still, right? I
hope to have
a reviewable copy on gerrit by Monday.

I do have a bizarre formatting problem -- who is the expert on how sphinx
handles
images? What I have formats beautifully in PDF but, in HTML, all the
screen shots
play out on the left of the screen (crammed together vertically) while the
headers
and other prose are on the right. I think it has something to do with .png
files in
close proximity to each other. I put page breaks between the sections
(which left
just one image per page) and I thought it had solved the problem but it has
not.

I can't put the User's Guide up for you to see right now but we have the
same problem
in the Express Release Notes:
http://docs.mirantis.com/express/master/release-notes.html,
right at the top -- those are three separate little screen shots with
headers and text between
them. Any ideas?

meg

On Fri, May 9, 2014 at 3:40 AM, Mike Scherbakov
<email address hidden>wrote:

> Is it done or still in progress?
>
> --
> You received this bug notification because you are a bug assignee.
> https://bugs.launchpad.net/bugs/1289668
>
> Title:
> docs: pre install guide quick install is visually un-readable
>
> Status in Fuel: OpenStack installer that works:
> In Progress
>
> Bug description:
> docs: fuel-docs/pages/pre-install-guide/0060-quick-install-fuel.rst
>
> http://docs.mirantis.com/fuel/fuel-4.1/pre-install-guide.html#configuring-fuel-using-the-iso-image
>
> The text between the images makes no sense
> The text and images show no structure
> There appears to be no purpose or goal
> The images have no visual breaking between each other and the text
> related to each image
> The images are not scaled to the size of the page (might not be fixable)
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/fuel/+bug/1289668/+subscriptions
>

[Meg McRoberts (dreidellhasa)]

I think we can call this fixed for 5.0. My immediate problem is that I
have a commit that
I can't submit for review -- I keep getting a database error from gerrit.
 So I am attaching
a PDF of the current draft -- I still need to rewrite the intro and I'm
missing a couple of
screen shots, plus I am hoping to get more supporting information and
cross-references
into it. And the Pre-Install Guide needs a lot more work than it is going
to get for this
release, although I will get a bit more done.

But, this LP is about the screens being unreadable and I think these screen
shots are quite
legible

On Wed, May 14, 2014 at 11:50 PM, Mike Scherbakov <
<email address hidden>> wrote:

> ** Changed in: fuel
> Milestone: 5.0 => 5.1
>
> --
> You received this bug notification because you are a bug assignee.
> https://bugs.launchpad.net/bugs/1289668
>
> Title:
> docs: pre install guide quick install is visually un-readable
>
> Status in Fuel: OpenStack installer that works:
> In Progress
>
> Bug description:
> docs: fuel-docs/pages/pre-install-guide/0060-quick-install-fuel.rst
>
> http://docs.mirantis.com/fuel/fuel-4.1/pre-install-guide.html#configuring-fuel-using-the-iso-image
>
> The text between the images makes no sense
> The text and images show no structure
> There appears to be no purpose or goal
> The images have no visual breaking between each other and the text
> related to each image
> The images are not scaled to the size of the page (might not be fixable)
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/fuel/+bug/1289668/+subscriptions
>

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/92075
Committed: https://git.openstack.org/cgit/stackforge/fuel-docs/commit/?id=8107f943cdf77e2f91ca01470d07956dcda8ebbc
Submitter: Jenkins
Branch: master

commit 8107f943cdf77e2f91ca01470d07956dcda8ebbc
Author: Meg McRoberts <email address hidden>
Date: Mon May 5 01:59:00 2014 -0700

    Set up User Guide

    This guide has been ordered to have sections that parallel
      what is in the introductory table, with screen shots, instructions,
      and appropriate xrefs in the same order as the table

    Moved info about mapping logical-to-physical NICS from pre-install
    Moved info about configuring the PXE network before deploying environment
      from install-guide
    Added information about booting node servers before deploying environment
    Deleted some superfluous and illegible screen shots that are now replaced
      by material in user-guide
    Added "Configure Hardware" from information that was in the pre-install
      "Prerequisites" table.

    TODO(Meg McRoberts):
      - Modularize the sections about each task/screen into separate
        files
      - Rewrite the intro (as well as the intros for Pre-Install and Install
      - A couple of screen shots are missing
      - Add xrefs to sections in other docs for supporting information.

    Closes-Bug: 1289668
    Closes-Bug: 1308279

    Change-Id: Ie717a0fafbf40272f603bab361046fa36457501a

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/5.0
Review: https://review.openstack.org/95314

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/95314
Committed: https://git.openstack.org/cgit/stackforge/fuel-docs/commit/?id=7acb4730388d9b90d038a7470b4b7409f08d9399
Submitter: Jenkins
Branch: stable/5.0

commit 7acb4730388d9b90d038a7470b4b7409f08d9399
Author: Meg McRoberts <email address hidden>
Date: Mon May 5 01:59:00 2014 -0700

    Set up User Guide

    This guide has been ordered to have sections that parallel
      what is in the introductory table, with screen shots, instructions,
      and appropriate xrefs in the same order as the table

    Moved info about mapping logical-to-physical NICS from pre-install
    Moved info about configuring the PXE network before deploying environment
      from install-guide
    Added information about booting node servers before deploying environment
    Deleted some superfluous and illegible screen shots that are now replaced
      by material in user-guide
    Added "Configure Hardware" from information that was in the pre-install
      "Prerequisites" table.

    TODO(Meg McRoberts):
      - Modularize the sections about each task/screen into separate
        files
      - Rewrite the intro (as well as the intros for Pre-Install and Install
      - A couple of screen shots are missing
      - Add xrefs to sections in other docs for supporting information.

    Closes-Bug: 1289668
    Closes-Bug: 1308279

    Change-Id: Ie717a0fafbf40272f603bab361046fa36457501a