Documentation is not friendly

[gswallow]

Version

None. Still working on an install.

Platform:

UPI on vsphere

What happened?

The documentation, particularly the section on platform customization, is poor.

https://github.com/openshift/installer/blob/master/docs/user/customization.md#platform-customization

I'm instructed to read Go docs. I can figure it out but c'mon. Do better.

What you expected to happen?

I expect to read a table in markdown format explaining how to create an install-config.yaml file.

How to reproduce it (as minimally and precisely as possible)?

Read the docs.

[gswallow]

Additionally, the official, redhat-supplied openshift-install binaries won't generate a skeleton install-config.yaml file for vSphere (the ones available at https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest/). Only AWS.

However, if I build my own openshift-install binary from git (specifically release 0.16.0), I can create a skeleton file for vSphere just fine.

Is the redhat-release (v4.1.1) installer intentionally crippled?

[wking]

A few points:

• docs/user: Standardize install-config property documentation #2162 is a WIP in flight to give you Markdown docs.
• Installer-repo docs are unofficial.
  • Here are the official vSphere docs. Better, but still not perfect.
  • Here are the official AWS docs, with the non-godoc detail we all aspire too.
• PRs welcome, if you can't wait for us to fix things ourselves :)
• Dunno what's going on with the vSphere wizard; I'll look later.

[gswallow]

Thanks!

My Golang skill are non-existent or I'd submit a PR.

[wking]

No Go required to fill in the Markdown docs you're asking for?

[gswallow]

Well I can do that! I'll take a closer look. I thought it'd be Go tooling to automatically fill out markdown docs.

…

On Wed, Aug 28, 2019 at 10:01 PM W. Trevor King ***@***.***> wrote: No Go required to fill in the Markdown docs you're asking for? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#2285?email_source=notifications&email_token=ABAHXKHFR2DHP4PIG6UOA6TQG4UWBA5CNFSM4IRMSG4KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD5M7PDA#issuecomment-525989772>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABAHXKDMQI27FL7YV2YATBDQG4UWBANCNFSM4IRMSG4A> .