Skip to content

[Docs] Caveats live only on the honesty page, not beside the claims #21

Description

@A13xB0

Problem

The site's honesty page carries caveats that the pages making the corresponding
claims do not repeat, so a reader who does not go looking is left with the
stronger impression.

Board support. what-it-does-not-do.md states that exactly one board,
Generic_E22_sx1262, passes every capability the board check asks of it, that
two more are green with a caveat, and that the rest either cannot be run at all
or run and then go quiet. emulation.md, native-vs-emulated.md and
firmware-library.md describe emulated boards without that proportion. Someone
choosing MeshBench to test their own board reads three pages about emulation and
meets the real state only if they open a fourth.

The Bluetooth companion. testing.md says a phone app "discovers and
connects to a simulated node exactly as it would to hardware". The honesty page
records that this is a host-side BlueZ GATT server, not MeshCore's own BLE
stack. The connection is genuine; what is being exercised is not the firmware's
Bluetooth code, which is the thing a phone-app developer would most reasonably
assume they were testing.

Why it matters

The site's own style guide makes this a rule: "Admit the limit in the same
breath as the claim. This is the one thing the site cannot afford to soften."
Keeping the limits accurate but filing them on a separate page softens them by
distance.

The board case is the one that costs a user real time: they install, pick their
board, and find out only then. The Bluetooth case risks a wrong conclusion
rather than wasted time — a developer could believe they have tested against
MeshCore's BLE implementation when they have not.

Location

  • pages/emulation.md
  • pages/native-vs-emulated.md
  • pages/firmware-library.md
  • pages/testing.md — the Bluetooth paragraph
  • pages/what-it-does-not-do.md — the source for both caveats (generated; do not
    edit here)

Recommended approach

Put one sentence on each page, next to the claim it qualifies, linking to the
fuller account. The wording already exists in the honesty page and should be
reused rather than reinvented, so the two cannot drift.

For boards specifically, a reader deciding whether the tool suits them wants the
proportion early — on emulation.md near the top, not in a footnote.

Acceptance criteria

  • Each of the three emulation pages states how many boards currently pass the
    board check, next to its claims about emulation
  • The Bluetooth paragraph says the peripheral is a host-side implementation
    rather than the firmware's own BLE stack
  • Each caveat links to the fuller account
  • Documentation matches current implementation
  • Links validated
  • Documentation site builds successfully

Release Impact

These are the claims most likely to send someone down a path the tool cannot yet
support, and the site's own register rule already requires the caveat to sit
beside the claim.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Before First ReleaseMust be resolved before the first public releaseP2Normal prioritydocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions