Bug 1860289

Summary:	FeatureGate documentation is incomplete and incomprehensible
Product:	OpenShift Container Platform	Reporter:	Stefan Schimanski <sttts>
Component:	Documentation	Assignee:	Michael Burke <mburke>
Status:	CLOSED CURRENTRELEASE	QA Contact:	MinLi <minmli>
Severity:	low	Docs Contact:	Vikram Goyal <vigoyal>
Priority:	low
Version:	4.5	CC:	aos-bugs, deads, jokerman, minmli, oarribas
Target Milestone:	---
Target Release:	4.5.z
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	If docs needed, set a value
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2021-05-06 17:52:07 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 Stefan Schimanski 2020-07-24 09:11:26 UTC

Document URL: https://docs.openshift.com/container-platform/4.5/nodes/clusters/nodes-cluster-enabling-features.html

Section Number and Name: all

Describe the issue: 

Comparing the doc page with the source code of the API (https://github.com/openshift/api/blob/master/config/v1/types_feature.go) shows that half of the API is not documented:

- we have 4 feature sets. One is only documented.
- it is completely lacking how to actually enable the listed feature gates.
- it is not explained what a feature set is.
- it is not explained how features and feature sets relate.

Suggestions for improvement: 

Rewrite most of it explaining what the concepts are. Give examples for sets and custom features. Make it complete.

Additional information:

Comment 1 David Eads 2020-07-24 12:44:39 UTC

I would remove the entire page.  This setting is only useful in the sense of trying to enable a specific profile like latencysensitive or ipv6dualstack.  Seems like you would document the featuregate settings where you talk about how to accomplish the goal of "I want to run applications that require colocation", or "I want ipv6dualstack without the ability to upgrade".

The customnoupgrade setting is really only useful to developers, so it seems like swagger satisfies them.

I'm not sure why we have this page at all.

Comment 3 Michael Burke 2020-08-17 20:27:13 UTC

David --

I like your idea of referencing the feature sets with the appropriate features. Not sure which topics require the info. The Topology Manager topic does mention the latencysensitive feature set [1].

In my opinion, we shouldn't remove the topic, as it is a feature and in both the CLI and the console. But not my decision to make.

Michael

[1] https://docs.openshift.com/container-platform/4.5/scalability_and_performance/using-topology-manager.html#seting_up_topology_manager_using-topology-manager

Comment 4 Michael Burke 2020-10-28 16:46:00 UTC

New docs PR: https://github.com/openshift/openshift-docs/pull/24132

Comment 5 Michael Burke 2020-10-28 16:46:53 UTC

Xiaoli -- Can you please assign this BZ to a QE resource for review? 

Thank you very much.

Michael

Comment 6 MinLi 2020-10-29 10:13:11 UTC

Hi,  Michael Burke
I comment on pr: https://github.com/openshift/openshift-docs/pull/24132 , please take a look.

Comment 7 Michael Burke 2021-05-06 17:52:07 UTC

Changes are live: https://docs.openshift.com/container-platform/4.6/nodes/clusters/nodes-cluster-enabling-features.html#nodes-cluster-enabling-features-console_nodes-cluster-enabling

Comment 8 Red Hat Bugzilla 2023-09-15 00:34:38 UTC

The needinfo request[s] on this closed bug have been removed as they have been unresolved for 500 days