Bug 1254844
| Summary: | [DOCS] [3.2] Break up, restructure, and reorganize the OSE 3.0 Admin Guide | ||
|---|---|---|---|
| Product: | OpenShift Container Platform | Reporter: | Bilhar <baulakh> |
| Component: | Documentation | Assignee: | Timothy <tpoitras> |
| Status: | CLOSED CURRENTRELEASE | QA Contact: | weiwei jiang <wjiang> |
| Severity: | high | Docs Contact: | Vikram Goyal <vigoyal> |
| Priority: | high | ||
| Version: | 3.0.0 | CC: | adellape, ahardin, jokerman, mmccomas, tpoitras, wsun |
| Target Milestone: | --- | ||
| Target Release: | --- | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | Bug Fix | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2016-09-28 00:54:18 UTC | Type: | Bug |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
| Embargoed: | |||
|
Description
Bilhar
2015-08-19 04:16:56 UTC
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. 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). 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 Thank you, Alex. I have mentioned this to Bilhar, and we'll take it into consideration during the restructure work. :) (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. (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. (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. I'm leaning towards Cluster Administration myself. xref: https://projects.engineering.redhat.com/browse/CCS-171 ^ The name change had some impact when trying to publish on the Customer Portal. https://github.com/openshift/openshift-docs/pull/2030 WIP, nearly done https://github.com/openshift/openshift-docs/pull/2030 This has passed both QE and Peer review now. |