Repository navigation
docs: write for the reader and settle conflicting facts - #1069
Merged
Merged
Conversation
- Quick start: document the Fd-App-Key header, response language
(locale / lang / Accept-Language), that data is {} or omitted when an
operation has no payload, and the timestamp/enum/update conventions.
Move limits and errors to one page instead of repeating them.
- Rate limits and errors: state the default per-account limits (read
50/s and 1,000/min, write 20/s and 300/min), the
Flashcat-Request-Rate-Limit-Delay header on 429, and a corrected error
code table (MethodNotAllowed is 405, ResourceNotFound means the object
does not exist, NoLicense covers plan, quota and credits).
- Pagination: limits and defaults vary per operation; list every
operation that accepts search_after_ctx; explain that on incident and
alert lists has_next_page stops at 1,000 items in page-number mode and
how to continue with the cursor.
- Point the Go SDK pages at the new error code anchor.
Review all 370 public operations against the backend implementation and
fix what a caller needs to use each endpoint from its page alone:
- Restrictions: rate limits now match the gateway (most write operations
are 300/min and 20/s, not the read tier), permissions list every
permission that grants the call, and audit and plan requirements are
stated where they apply.
- Enums: declare the full value set for status, type, mode and similar
fields and explain each value; open sets say so.
- Request and response schemas: add missing fields, remove fields the
server no longer accepts or returns, correct required lists, mark
fields that can be null, and state units (seconds, milliseconds,
nanoseconds) and defaults.
- Usage notes: correct behavior that was described wrongly (whole-object
replacement on several upserts, soft vs permanent deletes, inhibit rule
semantics, pagination limits) and move long descriptions out of the
page subtitle.
- Examples: every request and 200 response example validates against its
schema; operations without a payload show no data field.
- Shared components: data is optional in the success envelope, 403 is
documented on every operation, 429 documents the
Flashcat-Request-Rate-Limit-Delay header, the error code table matches
the server, and the APP Key scheme mentions the Fd-App-Key header.
- API catalog: add the five missing monitor folder operations (370 total).
- Rebuild the consolidated openapi.{en,zh}.json from the module specs.
Add five rules: integer enums must explain every value, required may only name declared properties, every operation documents 403, request and 200 response examples must match their schema, and operation descriptions stay within 220 characters.
AGENTS.md gains a Reader first section: a delete test and a refactor test for every paragraph, what belongs on a page versus what to write instead, and the opening and order for each page type. The three diverged glossary copies are merged into glossary.md; .claude/skills becomes a symlink to .agents/skills and the translate skill links to the root glossary. polish-document reads AGENTS.md instead of its own outdated standards.md.
Alert sources share one severity-mapping heading and gain lead sentences; Zabbix keeps one walkthrough with per-version tabs. Webhook payload tables live on the incident webhook page only, sample payloads use example values, and change integrations describe which events merge instead of key formulas. SSO pages state Flashduty settings in text.
Event codes become console labels, offline and roadmap content is removed, and duplicated tables (snooze presets, similarity, label links) now live on one page with links elsewhere. Template variables match the template engine, default values follow the console, and marketing and unsourced comparison claims are cut.
Tool names and return codes give way to observable behavior, the billing notice and scope rules each live on one page, and sandbox network access is described consistently.
Rule types match the rule form, recovery tables live in the quickstart, and the engine page keeps the settings operators configure while dropping internal delivery details.
Intake host, upload cadence, privacy option, SDK versions, CocoaPods support and carrier-name collection now agree with the SDKs. Samples use the real loader and package names, user IDs come from the app's own account system, and roadmap notes are removed.
Preset roles and custom menus, the APP Key location, member contact editing and API catalog counts now match the product. Permission and custom-menu pages no longer describe storage mechanics, and the OpenAPI introduction links to rate limits instead of copying them.
Conflicts in the OpenAPI introduction, pagination, catalog and Go SDK pages resolve to #1068's text, which already links to rate limits and describes pagination by behavior. The catalog total is 372: the 370 endpoints with reference pages plus gallery pin/unpin, matching the per-module counts.
The collected-data table already says iOS reports the carrier name over cellular; the privacy-policy template customers copy now says so too.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites the docs to the reader's level: what a customer sees, sets, and decides, not how Flashduty works inside. Also fixes facts that contradicted each other across pages.
Rules (new section in
AGENTS.md→ Writing and page design → Reader first)Sources: Diátaxis, GOV.UK content design, Nielsen Norman Group, Wikipedia lead-section guidance, Every Page is Page One, plus the Krug and Williams rules already in this file.
Changes by area
glossary.md(three copies had diverged)..claude/skillsis a symlink to.agents/skills.standards.mdremovedFacts settled from product code
PersonID/PersonName/Email.LabelsMD5,TitleEnglishandIntegrationTypedo not exist.browser.flashcat.cloud.defaultPrivacyLevel, defaultmask.Checks
mint broken-links: no broken links.mint validate: passed.scripts/api_path_redirects.py --check: passed.scripts/lint_openapi.py: passed.build.mjsandcheck.mjspass with 348 keys.docs.jsonis unchanged.Includes #1068
#1068 (API reference update) is merged into this branch. Merging this PR lands both.
Please confirm