Skip to content
This repository has been archived by the owner on Oct 12, 2023. It is now read-only.

Proposed documentation updates #148

Open
lee0c opened this issue Nov 15, 2019 · 2 comments
Open

Proposed documentation updates #148

lee0c opened this issue Nov 15, 2019 · 2 comments
Labels
enhancement New feature or request

Comments

@lee0c
Copy link
Contributor

lee0c commented Nov 15, 2019

Describe the request

Current documentation (primarily the main README file) is unclear in places and uses poor examples. Proposed changes (I am happy to make these if y'all OK any/all of them) in solution field.

Explain why Key Vault FlexVolume needs it

Current docs are confusing and misleading to users, especially users who are less familiar with YAML & Kubernetes ecosystem cooncepts.

Describe the solution you'd like

  1. In the Contents, split "Getting started" into "Installing" and "Using" (and, optionally, "YAML Specification") - otherwise users jump immediately to "Detailed use cases" which are very specific.
  2. Pull out specification details (YAML fields, the table nested under this use case) into a separate section on specifications rather than nested under individual setup options. Keep spec details specific to each implementation option listed as steps in that implementation option as well.
  3. Provide more descriptive examples. The current example in the main README lacks clarity, especially around the keyvaultobjectaliases field - "secrets.json" can lead users to think that the aliases are stored in a file called "secrets.json".
  4. Fix broken links for VMSS MSI implementations in first line of Using KeyVault FlexVol section.
  5. Generally update language to align with all options offered - some language is still indicative of SPN versus Pod Identity being the only available implementation options.

Happy to make these updates if y'all want, will add in other tweaks if there are suggestions.

Describe alternatives you've considered

N/a as it is a docs change

Additional context

None.

@lee0c lee0c added the enhancement New feature or request label Nov 15, 2019
@stewartadam
Copy link

It should also be noted in the docs that spaces must not be present after semicolon-separated values in the config values or else parsing errors occur (I would add that the errors are extremely unclear/unrelated to the root cause when this happens - for example it will complain that a config key like 'tenantid' or 'resourcegroup' provided is empty, when it is not)

@namoshizun
Copy link

+1. This is a very useful add-on but unfortunately the documentation is just not so comprehensible...

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants