Bug 1254844 - [DOCS] [3.2] Break up, restructure, and reorganize the OSE 3.0 Admin Guide
[DOCS] [3.2] Break up, restructure, and reorganize the OSE 3.0 Admin Guide
Status: CLOSED CURRENTRELEASE
Product: OpenShift Container Platform
Classification: Red Hat
Component: Documentation (Show other bugs)
3.0.0
Unspecified Unspecified
high Severity high
: ---
: ---
Assigned To: Timothy
weiwei jiang
Vikram Goyal
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2015-08-19 00:16 EDT by Bilhar
Modified: 2016-11-08 01:29 EST (History)
6 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2016-09-27 20:54:18 EDT
Type: Bug
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 Bilhar 2015-08-19 00:16:56 EDT
Document URL: 
https://docs.openshift.com/enterprise/3.0/admin_guide/overview.html

Describe the issue: 
The Admin Guide at the moment is too big, not structured well, and the topics are not categorized correctly.

Suggestions for improvement: 
Based on experience, industry practices, and feedback from other internal stakeholders the Admin Guide should be split up as follows:

Installation and Configuration (topic category)
This topic category should include all of the one-time installation and configuration topics. For example, the quick and advanced install topics should be moved here.

Administration (topic category)
This topic category should contain all other day to day admin tasks, excluding all installation related topics. Furthermore, this topic category should include sub-categories that will make it easy to find the relevant information.

It should be sub-categorized in a useful and well-organized manner so that customers can find the information easily.

For example, the sub-categories may be:
Routing
Authentication
High Availability
Networking
etc....

These should flow in a manner that replicate a standard customer workflow, if possible.


Additional information:
Comment 2 Timothy 2015-09-08 02:21:53 EDT
Created PR: https://github.com/openshift/openshift-docs/pull/947

Moved install and config stuff into its own category: Installation and Configuration

Renamed Administrator Guide to Administration.

Fixed lots of broken links from moving things around.

@Bilhar -- I know you want the Admin topics to flow in a logical manner. Do you have a suggested order? Or should I be asking SMEs for input on the logical order that an admin would do these tasks?

Also, I think that reordering the topics can be a separate PR. I think if @Bilhar is happy with this for now, let's merge this one (947) so there's less chance of it meaning messy rebases for others (or for me). There are a whole lot of files affected here.
Comment 5 Alex Dellapenta 2015-09-16 16:10:35 EDT
Tim,

I see https://github.com/openshift/openshift-docs/pull/947 renamed "Administrator Guide" to "Administration". What do you think about going even more specific and naming it "Cluster Administration"? Would be more informative/accurate at a glance, since we have also concepts of "project administrators" (who could also be developers) in OSE, who could presumably be looking for info on performing "Administration" tasks on their projects.

It also wouldn't affect any filenames/links if we just rename it in the build_cfg and leave the file names alone (which I think would be fine).
Comment 6 Alex Dellapenta 2015-09-16 16:17:58 EDT
And in case "Platform Administration" vs "Cluster Administration" comes up, we have precedent in the product that would favor "Cluster Administration" since "cluster-admin" is an existing role in OSE:

https://docs.openshift.org/latest/architecture/additional_concepts/authorization.html#roles
Comment 7 Timothy 2015-09-16 21:08:08 EDT
Thank you, Alex. I have mentioned this to Bilhar, and we'll take it into consideration during the restructure work. :)
Comment 8 Bilhar 2015-09-16 21:22:11 EDT
(In reply to Timothy from comment #7)
> Thank you, Alex. I have mentioned this to Bilhar, and we'll take it into
> consideration during the restructure work. :)

I personally think a more widely accepted term would be "System Administration" which means it's system-wide administration, which differentiates it from project level admin. 

Would "cluster administration" be more related to HA concepts, or not? 

At the end these were just suggestions, so I'm happy with whatever you guys decide.
Comment 9 Alex Dellapenta 2015-09-17 10:25:21 EDT
(In reply to Bilhar from comment #8)
> 
> I personally think a more widely accepted term would be "System
> Administration" which means it's system-wide administration, which
> differentiates it from project level admin. 

It is more widely used in general yes, though considering OpenShift is a distributed system of many components/hosts, might sound a bit singular for this case? The overall OpenShift instance/"system" in general is typically referred to as the cluster, over which the cluster-admin role has control.

Not totally against "System Administration", mostly thinking out loud at this point in this interest of finding the best title, if we're going to bother changing it. Just something slightly more specific than simply "Administration" seems appropriate.

> Would "cluster administration" be more related to HA concepts, or not? 

No. While the term "cluster" is used in various HA technologies, here we're getting that language from OpenShift being built on a Kubernetes cluster.
Comment 10 Bilhar 2015-09-17 20:31:19 EDT
(In reply to Alex Dellapenta from comment #9)
> (In reply to Bilhar from comment #8)
> > 
> > I personally think a more widely accepted term would be "System
> > Administration" which means it's system-wide administration, which
> > differentiates it from project level admin. 
> 
> It is more widely used in general yes, though considering OpenShift is a
> distributed system of many components/hosts, might sound a bit singular for
> this case? The overall OpenShift instance/"system" in general is typically
> referred to as the cluster, over which the cluster-admin role has control.
> 
> Not totally against "System Administration", mostly thinking out loud at
> this point in this interest of finding the best title, if we're going to
> bother changing it. Just something slightly more specific than simply
> "Administration" seems appropriate.

100% agree that we need something more specific than just "Administration". I'm still leaning towards "System Administration" but I'm happy with either "System Admin" or "Cluster Admin" and will leave it up to you guys to decide what's best. :)

> 
> > Would "cluster administration" be more related to HA concepts, or not? 
> 
> No. While the term "cluster" is used in various HA technologies, here we're
> getting that language from OpenShift being built on a Kubernetes cluster.

That sounds reasonable, but it still seems tied to a specific technology.
Comment 11 Timothy 2015-09-18 00:11:18 EDT
I'm leaning towards Cluster Administration myself.
Comment 12 Alex Dellapenta 2015-09-25 10:24:55 EDT
xref: https://projects.engineering.redhat.com/browse/CCS-171

^ The name change had some impact when trying to publish on the Customer Portal.
Comment 14 Timothy 2016-05-09 07:41:26 EDT
https://github.com/openshift/openshift-docs/pull/2030

WIP, nearly done
Comment 15 Timothy 2016-05-12 03:36:10 EDT
https://github.com/openshift/openshift-docs/pull/2030

This has passed both QE and Peer review now.

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