Skip to content

docs: fix 55 defects found by proofread + source revalidation - #40

Merged
krassx merged 1 commit into
mainfrom
worktree-docs-audit-research
Sep 3, 2026
Merged

docs: fix 55 defects found by proofread + source revalidation#40
krassx merged 1 commit into
mainfrom
worktree-docs-audit-research

Conversation

@krassx

@krassx krassx commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

A third-party proofread of the docs site produced ~50 findings. Those were revalidated against the working tree, audited a second time adversarially, and then checked against the actual SDK and backend source in the sibling repos under ~/Projects/Bugsee. This PR applies the 55 that survived.

Won't compile as printed

File Defect
sdk/ios/manual.mdx Stray comma breaking an ObjC keyword message; extendedReport used where the block parameter is report; Swift if with no braces; ObjC/Swift "equivalent" label samples diverged
sdk/ios/privacy/video.mdx Swift tab assigned = YES
sdk/ios/custom.mdx Data(contentsOf:) called without try inside a non-throwing delegate method
sdk/dotnet/installation.mdx options.monitorNetwork — the property is MonitorNetwork
sdk/android/v6/custom.mdx Java tab used Report.Type.Crash; on release-6, Report.getType() returns IssueType and no such nested enum exists
sdk/android/v6/maven-installation.md </manifest missing its closing bracket
integrations/recipes/recipes_issues.mdx Missing comma made the context sample invalid JavaScript

Wrong facts, settled against source

  • migration.mdx sent v6→v7 upgraders to Options.DetectAndReportCrashNdk. It is NdkOptions.DetectAndReport in the bugsee-android-ndk module.
  • configuration/ndk.mdx told readers to import com.bugsee.library.ndk.contracts.options.NdkOptions and said the constants "live in the extension's own package". That class is @Deprecated and its Javadoc says the opposite — the keys moved to com.bugsee.library.contracts.options.NdkOptions.
  • PerformanceAdaptiveSampling was described three different ways across two pages. Options.java and AdaptiveSampler.java show it promotes transactions that lost the random draw, scored at finish time on status, duration outlier-ness and span-tree complexity. So the static rate is a floor; the documented "ceiling" was backwards on two pages.
  • ios/configuration.mdx named the constant BugseeCaptureDeviceAndNetworkNamesKey. BugseeConstants.h declares it without the Key suffix — the one option constant in the header that lacks it.
  • captureDeviceAndNetworkNames is genuinely platform-split (iOS NO, Android true). Six wrapper pages each flattened it to a single value repeated across both their iOS and Android tables. Each section now carries its own default. (The proofread reported a .NET-vs-Xamarin contradiction; that pair does not exist.)
  • defaultBugPriority was Low in Unity, React Native and Cordova. Android registers IssueSeverity.High and iOS defaults to BugseeSeverityHigh.
  • "default log level (normal)" — no such level exists. It is info, per the Flutter enum annotation and Cordova's level || LogLevel.Info. Fixed in 9 files.
  • Simulator support was given as v7.0.0 (Cordova) and v9.0.0 (Flutter). It shipped in iOS 6.0.0.
  • flutter/release-notes.md displayed 5.5.8 against the 5.5.7 anchor. The anchor was wrong — 8.6.6 already ships 5.5.8, so changing the version text would have invented a regression.
  • .NET: duplicate FrameRate row, wrong enum format in the iOS table, stale "1MB" attachment limit, and Xamarin-Studio-era symbolication instructions.
  • ios/symbolication.mdx omitted two on-by-default env vars documented elsewhere.
  • KMP told readers to pin the version and then showed :+. Pinned to 0.1.1 per version.txt.

⚠️ Retired integrations still documented as working

appserver/config/default.js carries an integrations.retired map. Bitbucket (Cloud removed its Issues REST API on 2026-08-20) and Pivotal Tracker (discontinued 2025-04-30) both throw IntegrationProviderRetiredError on push, but both had full setup guides with no notice and were listed as live on the integrations index. Added retirement notices.

This needs your review — I wrote conservative warnings pointing at Jira / the integrations list, but whether these pages should be redirected or removed outright is a product call.

Deliberately not changed

  • http_engine in the Gradle plugin table is correct. Both the proofread and my own first pass called it a casing bug. That column lists registrar keys, and HttpEngineInstrumentation.kt declares override val key = "http_engine". The source comment is explicit: "snake_case is the canonical registrar key; camelCase alias matches the DSL property name."
  • android/v6/release-notes.md ordering — a script over all 175 entries found zero violations. The file is version-descending by repo convention.
  • compileSDKVersion casing appears in 7 shipped historical release notes. Rewriting published notes is an editorial call, so I left it.
  • Android version banners now read 7.x rather than 7.1, so they stop going stale at each point release. Say the word if you'd rather pin them.

Also worth knowing

Nozbe is a live integration (in the providers enum, with both an integrator and an OAuth module) that has no documentation page at all. Its row in the markup-support table is correct and was kept; Hipchat and Testlio were removed, the latter confirmed by migration 056-remove-testlio-integrations.

Findings that did not survive

Four proofread claims and several of my own intermediate conclusions were wrong and are not in this PR — a duplicate Zoho Desk heading, a missing "and" in YouTrack, the .NET/Xamarin default pair, the v6 release-note ordering, and a React Native grammar error that was already correct on main. The MCP tool-count and scope findings were real but had already been fixed on main; only the three AI-plugin pages still claimed the server is read-only.


npx cspell clean across 288 files; npm run build succeeds. The two SSG warnings on sdk/dotnet/network and sdk/xamarin/network are pre-existing and untouched.

🤖 Generated with Claude Code

Third-party proofread findings, revalidated against the working tree and
then against the actual SDK/backend source under ~/Projects/Bugsee.

Code samples that did not compile as printed:
- ios/manual.mdx: stray comma in an ObjC keyword message; undefined
  `extendedReport` (the block parameter is `report`); Swift `if` without
  braces; ObjC/Swift label samples diverged
- ios/privacy/video.mdx: Swift tab used `= YES`
- ios/custom.mdx: `Data(contentsOf:)` called without `try` in a
  non-throwing delegate method
- dotnet/installation.mdx: `options.monitorNetwork` -> `MonitorNetwork`
- android/v6/custom.mdx: Java tab used `Report.Type.Crash`; no such nested
  enum exists in v6 (release-6 `Report.getType()` returns `IssueType`)
- android/v6/maven-installation.md: unclosed `</manifest` tag
- recipes_issues.mdx: missing comma made the context sample invalid JS

Wrong facts, corrected against source:
- android/migration.mdx: v6->v7 table pointed at `DetectAndReportCrashNdk`;
  it is `NdkOptions.DetectAndReport` in the bugsee-android-ndk module
- android/configuration/ndk.mdx: told readers to import the @deprecated
  `com.bugsee.library.ndk.contracts.options.NdkOptions`; the keys moved to
  `com.bugsee.library.contracts.options.NdkOptions`
- PerformanceAdaptiveSampling was described three different ways across two
  pages. Per Options.java + AdaptiveSampler.java it promotes transactions
  that lost the random draw, scored at finish time — so the static sample
  rate is a floor, not the documented "ceiling"
- ios/configuration.mdx: `BugseeCaptureDeviceAndNetworkNamesKey` does not
  exist; the constant has no `Key` suffix
- captureDeviceAndNetworkNames: the native default is platform-split
  (iOS NO, Android true). Six wrapper pages each flattened it to one value
  across both their iOS and Android tables
- defaultBugPriority documented as Low in Unity/RN/Cordova; Android
  registers IssueSeverity.High and iOS defaults to BugseeSeverityHigh
- "default log level (normal)": no such level. It is `info`
- simulator support: Cordova said v7.0.0 and Flutter v9.0.0; it shipped in
  iOS 6.0.0
- flutter/release-notes.md: 5.5.8 entry linked the 5.5.7 anchor
- dotnet: duplicate FrameRate row, wrong enum format, stale 1MB attachment
  limit, Xamarin-era "Project options -> Compiler" instructions
- ios/symbolication.mdx: env-var table omitted two on-by-default vars
- kmp: page said to pin the version, then showed `:+`; pinned to 0.1.1
- Bitbucket and Pivotal Tracker are retired at the backend (appserver
  config `integrations.retired`) but documented as working — added
  retirement notices

Also: MonitorDiskSpace descriptions, Unity GF->BG->FG typo, stray table
separator rows, triple-backtick spans in table cells, heading levels on
iTop/Redmine/Zoho Desk, GitHub/GitLab/Bitbucket/Jira casing, six missing
`sidebar_position` fields, Android version banners pinned at 7.0.0, and
assorted grammar.

Not changed, deliberately:
- `http_engine` in the Gradle plugin table is correct. That column lists
  registrar keys, and HttpEngineInstrumentation declares `"http_engine"`
- android/v6/release-notes.md ordering is version-descending by convention
- `compileSDKVersion` casing in shipped release notes — left for review

cspell clean; `npm run build` succeeds.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Change-Id: I30a1cbfa0cfb800bcf9b24bd99d3265c440ec5ef
@krassx
krassx merged commit fabdd60 into main Sep 3, 2026
1 check passed
@krassx
krassx deleted the worktree-docs-audit-research branch September 3, 2026 06:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant