Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Fix Eventing State doc formatting #502

Merged
merged 3 commits into from
Feb 22, 2024

Conversation

muralov
Copy link
Contributor

@muralov muralov commented Feb 19, 2024

Description

Fix eventing state doc formatting

Related issue(s)
#328

@muralov muralov requested a review from a team as a code owner February 19, 2024 20:24
@kyma-bot kyma-bot added area/documentation Issues or PRs related to documentation cla: yes Indicates the PR's author has signed the CLA. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Feb 19, 2024
docs/user/02-configuration.md Outdated Show resolved Hide resolved
docs/user/02-configuration.md Outdated Show resolved Hide resolved
docs/user/02-configuration.md Outdated Show resolved Hide resolved
- The <b>Backend Config</b> column is part of the eventing CR that is either available or mistakenly not specified by a user.
- The <b>Backend State</b> column describes the state of the NATS backend or EventMesh Secret existence.
- The <b>Backend State</b> column describes the state of the NATS backend or EventMesh Secret existence.
- The <b>Eventing State</b> column has the overall state of the Eventing CR.

Warnings indicate that user action is required, that is, the user must install the NATS module or create an EventMesh Secret.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In line 89, "Impact on Event Flow" must be in title case because it's a heading.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general, how about the following order of rows and columns:

Suggested change
| Backend Type | Backend Config | Backend State | Eventing State | Impact on Event Flow |
|----------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------|------------------------------------------|
| NATS/EventMesh | missing | n/a | Warning | No events will be accepted or dispatched |
| NATS/EventMesh | exists | Processing (mainly happens during initialization and backend switching) | Processing | No events will be accepted or dispatched |
| NATS | exists | Warning (NATS deletion blocked) | Ready | Events will be accepted or dispatched |
| NATS | exists | Error (NATS ist unavailable or cannot be connected) | Warning | No events will be accepted or dispatched |
| NATS | exists | Missing | Warning | No events will be accepted or dispatched |
| EventMesh | exists | Error (secret for EventMesh missing) | Warning | No events will be accepted or dispatched |
| NATS/EventMesh | exists | Error (cases not caused by a user, such as cannot create EPP deployment or cannot start subscription manager although backend is available) | Error | No events will be accepted or dispatched |

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We discussed the order with Korbinian and we agreed to this order. Why do you want to change it?

Copy link
Contributor

@NHingerl NHingerl Feb 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because I think a) backend missing or existing is the first important distinction; with a missing backend, all later steps are irrelevant. That's why I pulled that row up. I also added "n/a" to that field, so that there's no misunderstanding whether we simply forgot to enter information there.

Furthermore, because as a user, I think it's easiest to know whether I have NATS or EventMesh, so I pulled that column to the first position.
This also matches the fact that this is about the impact of the backend to the Eventing CR State and Event Flow; so the focus is on the backend. Conversely, if the purpose of the table had been "Understanding the causes of the Eventing state"; I'd pull the "Eventing State" column to the first position.

In general, I personally find option A easier to understand than option B:

Option A
image

Option B
image

docs/user/02-configuration.md Outdated Show resolved Hide resolved
@kyma-bot kyma-bot added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Feb 20, 2024
@muralov muralov force-pushed the fix-eventing-state-doc-format branch from 255dd0c to c787271 Compare February 22, 2024 13:07
@kyma-bot kyma-bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Feb 22, 2024
@kyma-bot kyma-bot added the lgtm Looks good to me! label Feb 22, 2024
@kyma-bot kyma-bot merged commit d20139a into kyma-project:main Feb 22, 2024
3 checks passed
@muralov muralov deleted the fix-eventing-state-doc-format branch February 22, 2024 14:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/documentation Issues or PRs related to documentation cla: yes Indicates the PR's author has signed the CLA. lgtm Looks good to me! size/M Denotes a PR that changes 30-99 lines, ignoring generated files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants