Update shared content topics #5845
Conversation
clayton-cornell
added
type/docs
docs/sources/shared/flow/reference/components/otelcol-filter-resource-block.md
Outdated
Show resolved
Hide resolved
| `credentials_file` | `string` | File containing the secret value. | | no | ||
| `credentials` | `secret` | Secret value. | | no | ||
| `type` | `string` | Authorization type, for example, "Bearer". | | no |
There was a problem hiding this comment.
I'm not convinced that the tables should be alphabetized. Having custom ordering for the tables means we can group related arguments together, even if they don't have similar ordering, and allows us to order things in a way that increases in increasing argument specificity, with more general and common arguments towards the top of the list.
(And for a less compelling argument, people usually see forms as "username and password" but alphabetical sorting means that we're presenting it as "password and username", which is slightly jarring but not a huge deal).
There was a problem hiding this comment.
I agree with @rfratto. Also, sorting rows alphabetically will be an extra burden when writing docs :/
There was a problem hiding this comment.
@rfratto @ptodev I did some research on this over the past 3 days, and consulted the Grafana doc team as well. The advice is to sort lists/tables alphabetically unless the order is important to understanding the information in the list/table (for example required vs optional arguments). This guideline will be added to the Grafana Writer's Toolkit.
Semantic sorting does work (username/password is a great example), but sorting this way adds its own overhead to the doc maintenance. One person's ordering (for example sorting most-used to least used things) isn't always the next person's ordering. Semantic sorting also requires that the SME (developer/community contributor) knows where in the existing lists/tables to insert new arguments. Some people place new content at the bottom of the table/list, some in the middle. It's pretty subjective and very difficult to validate.
Other precedents for sorting alphabetically can be found in OSS documentation such as Linux man pages (which sort command arguments alphabetically) - example: https://man7.org/linux/man-pages/man1/ssh.1.html
There was a problem hiding this comment.
Ack, I'm fine with this outcome. Plus, this is something we could undo in the future if alpabetical sorting turns out to cause unforeseen issues.
There was a problem hiding this comment.
Yes, there's always a path back if it isn't working for some reason.
docs/sources/shared/flow/reference/components/loki-server-grpc.md
Outdated
Show resolved
Hide resolved
docs/sources/shared/flow/reference/components/otelcol-debug-metrics-block.md
Outdated
Show resolved
Hide resolved
docs/sources/shared/flow/reference/components/rule-block-logs.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Robert Fratto <[email protected]>
docs/sources/shared/flow/reference/components/otelcol-debug-metrics-block.md
Outdated
Show resolved
Hide resolved
* Update layout and syntax in shared topics * Updates to language passive voice use etc * General updates to words syntax and voice * Fix sorting in table * Fix table spacing * Correct capitalization of boolean * Apply suggestions from code review Co-authored-by: Robert Fratto <[email protected]> * Update docs/sources/shared/flow/reference/components/otelcol-debug-metrics-block.md --------- Co-authored-by: Robert Fratto <[email protected]> (cherry picked from commit dcfdce5)
* Update layout and syntax in shared topics * Updates to language passive voice use etc * General updates to words syntax and voice * Fix sorting in table * Fix table spacing * Correct capitalization of boolean * Apply suggestions from code review Co-authored-by: Robert Fratto <[email protected]> * Update docs/sources/shared/flow/reference/components/otelcol-debug-metrics-block.md --------- Co-authored-by: Robert Fratto <[email protected]> (cherry picked from commit dcfdce5)
* Update layout and syntax in shared topics * Updates to language passive voice use etc * General updates to words syntax and voice * Fix sorting in table * Fix table spacing * Correct capitalization of boolean * Apply suggestions from code review Co-authored-by: Robert Fratto <[email protected]> * Update docs/sources/shared/flow/reference/components/otelcol-debug-metrics-block.md --------- Co-authored-by: Robert Fratto <[email protected]> (cherry picked from commit dcfdce5) Co-authored-by: Clayton Cornell <[email protected]>
* Update layout and syntax in shared topics * Updates to language passive voice use etc * General updates to words syntax and voice * Fix sorting in table * Fix table spacing * Correct capitalization of boolean * Apply suggestions from code review Co-authored-by: Robert Fratto <[email protected]> * Update docs/sources/shared/flow/reference/components/otelcol-debug-metrics-block.md --------- Co-authored-by: Robert Fratto <[email protected]> (cherry picked from commit dcfdce5) Co-authored-by: Clayton Cornell <[email protected]>
github-actions
bot
added
the
frozen-due-to-age
PR Description
This PR is the first of several focused on a cleanup of the Agent Flow component reference documentation.
This PR updates the shared content topics (Flow reference docs). Changes include:
NOT included:
Which issue(s) this PR fixes
Notes to the Reviewer
PR Checklist