Note: This bug is displayed in read-only format because the product is no longer active in Red Hat Bugzilla.

Bug 456146

Summary:	Installation flowchart needed
Product:	Red Hat Directory Server	Reporter:	Rich Megginson <rmeggins>
Component:	Doc-installation-guide	Assignee:	Deon Ballard <dlackey>
Status:	CLOSED WORKSFORME	QA Contact:	Content Services Development <ecs-dev-list>
Severity:	low	Docs Contact:
Priority:	low
Version:	8.0	CC:	ckannan
Target Milestone:	DS8.1	Keywords:	Documentation
Target Release:	---
Hardware:	All
OS:	All
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2009-03-13 02:14:08 UTC	Type:	---
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:
Bug Depends On:
Bug Blocks:	249650

Description Rich Megginson 2008-07-21 18:15:34 UTC

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-22 00:10:09 UTC

(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 15:51:01 UTC

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-13 02:14:08 UTC

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.