replicatedhq/replicated-docs

Docs feedback

Closed this issue · 6 comments

markpundsack commented

On https://docs.replicated.com/reference/custom-resource-redactor:

The example is pretty useless. I mean, it shows the YAML structure, but it doesn't show a meaningful example since the redactors key is just an empty array. What does the content of that array look like? What's a practical example?

paigecalvert commented

Thanks @markpundsack -- we're currently writing up an Epic related to adding more detail to the reference topics for the Troubleshoot features. I'll follow back up on this issue when those stories are written to provide a link.

paigecalvert commented

@markpundsack, following up to let you know that several improvements to this topic have been merged and are now live: https://docs.replicated.com/reference/custom-resource-redactor

Jonquil made these changes and had them reviewed as part of #507

The topic now includes:

  • Additional introductory content
  • Details on the fileSelector and Removals objects
  • A more useful example

Please let us know of additional improvement opportunities that you see by opening another issue, story, and/or PR, and we'll be happy to continue to iterate. Thank you!

markpundsack commented

Thanks, it's much improved!

I'd suggest the "Basic Manifest" File section should probably be deleted, since the example is much clearer, but I see that it's similar to what we do for Preflights.

Separate note but the example redacts passwords, but we automatically redact any passwords, so it's not very realistic in the sense that somebody would use that particular example. It's illustrative of how to specify redactors though, so it's very useful. I wonder if we can come up with one that isn't included automatically?

paigecalvert commented

Good notes--yes, agreed that it would be better to find an example that isn't already included automatically, to make it more realistic. I'll make a story for this.

I also see what you're saying on the Basic Manifest section. It was probably one of those things where it was there already, and so it stuck around. I think we assumed there was some value to a standard blank template, though with the example(s), I can see how it's more than likely unnecessary. I'll raise with Jonquil when she's back next week; she's currently working on some PRs to update the preflight and support bundle reference topics accordingly, so we could likely just remove this from all of them at the same time to keep it consistent.

Thanks again!