Bug 456146 - Installation flowchart needed
Installation flowchart needed
Status: CLOSED WORKSFORME
Product: Red Hat Directory Server
Classification: Red Hat
Component: Doc-installation-guide (Show other bugs)
8.0
All All
low Severity low
: DS8.1
: ---
Assigned To: Deon Ballard
Content Services Development
: Documentation
Depends On:
Blocks: 249650
  Show dependency treegraph
 
Reported: 2008-07-21 14:15 EDT by Rich Megginson
Modified: 2009-08-19 23:36 EDT (History)
1 user (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2009-03-12 22:14:08 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Rich Megginson 2008-07-21 14:15:34 EDT
This is a request from a long time user of directory server:

The first major problem is that the documentation is not clear.
While RH has to support many different versions of product and operating systems
all at the same time, putting all the installation documentation for all
supported platforms makes it confusing to follow.

I would recommend that you have a simple graphic of a flow-chart that
asks newbies questions about what they're doing:

- Which operating system and version? (if not detectable)
- Which version of the directory server? (if not detectable)
- New or Upgrade? (existing install can be detected)
- Do you want Admin Console or not?

And let the answer to each node of the decision-tree lead to exactly one
very simple document that only speaks about what they're trying to do.
Having to wade through many unnecessary details in the document slows
down the process for new installs.
Comment 1 Deon Ballard 2008-07-21 20:10:09 EDT
(Thanks, Rich, for all the clarifications and help.)

I think part of the problem was that the link on the front page pointed to the
7.1 docs; this was the latest release when FDS 1.0 came out. (The link to the
install guide on the documentation page had been correctly updated to 8.0.)
Anyway, the 7.1 docs did combine the processes for the platforms; the
arrangement of the guide was that one chapter was about express installation,
one about typical, one about custom, and RHEL and Sun procedures were then
combined under each chapter. I can see how that would be confusing. The 8.0
install doc is organized with a chapter for each platform, so it should be more
clear, as the customer indicates.

There isn't exactly a decision tree as he requests, but there is an overview of
the setup process at
http://www.redhat.com/docs/manuals/dir-server/install/8.0/Installation_Guide-Preparing_for_a_Directory_Server_Installation-Installation_Overview.html.

I think the table on that page is similar to what he's asking for. A flow chart
isn't a bad idea to improve the 8.1 docs, charting the major steps for the three
different setup procedures (new, upgrade, migration). I don't think updating the
8.0 docs is necessary, though.

For his four points:
1. "Which OS" -  The chapters are broken down by OS, so it should be clear, and
the setup script is the same on any platform, so they just go to the
platform-appropriate install chapter and they're golden.

...and...

4. "Do you want admin console or not?" - Back in 7.1, you could select which
individual components to install as part of the setup. In 8.0, you can do that,
too, sort of, but it's not documented. Personally, I don't think it's such a
huge deal that it needs added to the 8.0 docs, but I can add it in 8.1. (If I'm
wrong, I can update the 8.0 docs, too.)

The other two seem to relate to migration.
2. "Which version of DS" - I assume this is for an in-place upgrade? Right now,
for 7.1 => 8.0, upgrade isn't supported (I believe), but something should be
included for 8.0 => 8.1. The migration chapter could definitely be better
organized. The migration script doesn't prompt for the version number on a
pre-8.0 DS, it just accepts it, but I can make a clear delineation between an
upgrade and a migration and between what to do on different platforms.

...and...

3. "New or Upgrade" - I don't know what the behavior will be, exactly, for 8.0
=> 8.1. IIRC, in 7.1, you would enter the info for the old server in the setup
script, and it would simply install the new server over the existing server.
Maybe something similar? 

So, after rambling around, I think:
1. Nothing really needs done to the 8.0 docs. (I'm crossing my fingers for that
one.)
2. A flow chart for install/upgrade/migration is good for 8.1.
3. The migration chapter could use some better clarity for a) migration v.
upgrade and b) different platforms.
Comment 2 Rich Megginson 2008-07-22 11:51:01 EDT
Setup should already know - what the OS is - what the DS version is - if there
is an existing installation that can be upgraded in place.  For 8.1, we'll have
to enhance setup, probably by the addition of a -r (reconfig) or -u (upgrade)
option, that by default will just do the right thing if setting up a new version
on top of an existing version.
Comment 3 Deon Ballard 2009-03-12 22:14:08 EDT
All of the migration and upgrade procedures have been updated for 8.1. I dppn't think anything needs to be done specifically for this. I'm closing the bug.

Note You need to log in before you can comment on or make changes to this bug.