Skip to content

Commit 7c6a3fa

Browse files
Guarislena-larionovakong-ksai[bot]
authored
Feat(platform): New KSAI rule to catch information overload (#7585)
* test * Update .ksai/ksai.toml Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> * Update .ksai/review-rules/core.md Co-authored-by: kong-ksai[bot] <313415923+kong-ksai[bot]@users.noreply.github.com> --------- Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> Co-authored-by: kong-ksai[bot] <313415923+kong-ksai[bot]@users.noreply.github.com>
1 parent c45d171 commit 7c6a3fa

3 files changed

Lines changed: 61 additions & 1 deletion

File tree

‎.ksai/ksai.toml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,25 @@ paths = [
3030
]
3131
source_files = ["review-rules/core.md"]
3232

33+
[[review.packs]]
34+
name = "Information overload"
35+
paths = [
36+
"app/**/*.md",
37+
"!app/_how-tos/**",
38+
"!app/_kong_plugins/**",
39+
"!app/_event_gateway_policies/**",
40+
"!app/_ai_policies/**",
41+
"!app/_mesh_policies/**",
42+
"!app/_references/**",
43+
"!app/_changelogs/**",
44+
"!app/_schemas/gateway/plugins/**",
45+
"!app/_includes/deck/help/**",
46+
"!app/_includes/kongctl/help/**",
47+
"!app/_api/**",
48+
"!api-specs/**",
49+
]
50+
source_files = ["review-rules/overload.md"]
51+
3352
[[review.packs]]
3453
name = "How-tos"
3554
paths = ["app/_how-tos/**/*.md"]

‎.ksai/review-rules/core.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Post at most one finding per rule per PR. List repeats in the same comment.
2222

2323
## Raise as a question, never a suggestion
2424

25-
- Whether to split a long step, reorder a section, or move a limitation under its own heading, when the order clearly fights the reader's sequence.
25+
- Whether to split a long step, reorder a section, or move a limitation under its own heading, when the order clearly fights the reader's sequence. Whole-page length on concept and reference pages is covered by `overload.md`; do not raise it here.
2626
- A new option, field or step says what it does but not why. Write a suggestion only if the page or a linked reference states the reason.
2727
- A step or block looks wrong for a platform in `works_on` (for example, an on-prem command on a Konnect-only page).
2828

‎.ksai/review-rules/overload.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Information overload
2+
3+
Applies to hand-written concept and reference pages (`content_type: reference` or `concept`). Skip the page if it is a how-to, a plugin or entity page, a changelog, a glossary, or a lookup page whose length comes from one large table or schema-driven field list.
4+
5+
Post at most one finding per PR. Raise it as a question, never a rewrite.
6+
7+
## When to fire
8+
9+
Fire only when the PR makes a significant edit to the page. That means it adds or substantially rewrites a section: a new H2 or H3, roughly 150 or more added words of prose, a new code block, or a new tab group.
10+
11+
Do not fire on typo fixes, wording or link tweaks, renames, or small edits that leave the page structure unchanged. Do not fire when the PR only moves existing content.
12+
13+
## What counts as overloaded
14+
15+
Judge the page as it reads after the PR. Flag when it has at least one size signal and at least one mixed-jobs signal.
16+
17+
**Size signals** (the 95th percentile of reference pages is about 2,100 words and 18 headings):
18+
- More than about 2,000 words of prose, not counting code blocks.
19+
- More than 18 headings in total, or more than 8 H2s.
20+
- More than 10 H3s on the page.
21+
22+
**Mixed-jobs signals.** The page does three or more of these jobs at once:
23+
- Explains a concept.
24+
- Provides a lookup table or field list.
25+
- Helps the reader decide between options ("when to use X instead of Y").
26+
- Describes behavior per product or platform.
27+
- Walks through configuration, with steps or tabs.
28+
- Lists limitations.
29+
30+
## How to report
31+
32+
Name the signals you measured, for example "about 3,400 words, 19 headings, and the page explains the concept, compares options, and walks through setup for four credential types". Ask whether the page should be split.
33+
34+
Suggest a split point only when the page itself supports it, such as step-by-step configuration that could be a how-to, or a decision guide that could stand alone. Do not write replacement text.
35+
36+
## Do not flag
37+
38+
- Length that existed before the PR when the diff adds no section.
39+
- Pages that are long because they are generated or table-driven.
40+
- Partner-authored third-party plugin prose.
41+
- A page the PR is already splitting or trimming.

0 commit comments

Comments
 (0)