Skip to content

docs: mark release-notes bug fixes as bug fixes, add the legend, standardize terminology and links - #94

Merged
MoKranda merged 2 commits into
mainfrom
docs/release-notes-markers-and-terminology
Oct 5, 2026
Merged

MoKranda merged 2 commits into
mainfrom
docs/release-notes-markers-and-terminology

Conversation

@rweesner

@rweesner rweesner commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Marks release-notes bug fixes as bug fixes and adds the marker legend, replaces
the remaining verb forms of "execute", swaps a routable example address for a
documentation-reserved one, and standardizes relative links on the .md form.

21 files, two commits. No content was rewritten beyond the lines listed below.

Release notes

Every one of the 88 entries carried the enhancement marker (:eight_spoked_asterisk:)
and none carried the bug-fix marker (:white_check_mark:), so a reader could not tell
a new feature from a fix. The page's own description promises "new features,
improvements, and bug fixes", and many entries already sit under Fixes headings —
the markers contradicted the structure they were in.

  • 64 entries now carry the bug-fix marker: every entry under a Fixes heading, plus
    eight corrective entries in 20.2.0–20.4.0 that have no sub-heading and open with
    "Fixed an issue".
  • Two entries that read as updates (WIN-566 in 20.1.0, and the Advanced Failure
    Criteria description change in 17.1.0) are marked as fixes because they are filed
    under Fixes. This follows the page's existing classification rather than
    reclassifying anything — worth a glance if either was really an enhancement.
  • The other 24 entries are features and keep the enhancement marker.
  • Added the legend used by the core OpCon release notes, so both markers are
    explained on the page.

Only the marker token changed on each line; no entry text was edited.

This restores the page's earlier state. Until the April 2026 documentation update the page
used both markers — 64 bug fixes and 22 enhancements — and that update replaced every marker
with the enhancement marker. Checked entry by entry against the page as it stood before April,
all 86 entries that existed then now carry exactly the marker the release authors gave them.
The two entries added since (25.2) are enhancements.

Terminology

Replaced seven verb forms of "execute" with "run", including the landing page's
description of what the agent does. Two things are deliberately left as they are:
"execute rights", which is the name of a Windows file permission, and "executable"
as a noun.

Remaining banned UI terms (second commit)

Five instances the first pass missed: "dialog box" and "dialog" are now "window",
"Select the Services icon" is now "Select Services" (twice), and "cannot be
launched" is now "cannot be started".

Example address

The AllowedIPAddress_1 example used 126.40.90.231, a routable address in an
allocated block. Changed to 192.0.2.10, from a range reserved for documentation
(RFC 5737) so that an example cannot point at a live host.

Links

Relative links were split between two styles — 29 with the .md extension and 33
without. All 62 now use the .md form. Every link resolved before and after the
change.

Verification

  • 0 bug fixes marked as enhancements; legend present.
  • 0 dead links, 0 broken anchors, 0 orphan pages — unchanged by the link edits.
  • 62 of 62 relative links in the .md form.
  • One remaining "execute", the permission name, by design.
  • The site builds with no broken-anchor warnings.

Follow-ups for an owner

Not changed here, each needing a decision rather than an edit:

  1. onBrokenAnchors is unset, so it defaults to warn, while onBrokenLinks is
    set to throw. This site currently has zero broken anchors, so setting it to
    throw would cost nothing today and would stop regressions. Not changed here
    because it alters build behavior for every contributor.
  2. administration/manage-lsam.md puts the legacy term in a published URL. Every
    visible string on the page already says "agent" — the title is "Managing the
    Windows Agent" — so this is the only avoidable instance of the term on the site.
    Renaming it needs a redirect. (The other occurrences are all identifiers such as
    MSLSAM.ini and the SMA_MSLSAM_* variables, or the LSAM Feedback category,
    which is a UI label and must match the product.)
  3. "Right-click" appears in 13 procedure steps. The documentation standards ban
    "click" and "right-select" but give no approved wording for the secondary-button
    action, while the Microsoft Writing Style Guide they defer to uses "right-click".
    Left alone until there is an agreed form.
  4. The noun "execution" appears 21 times. The standards list "execute" under
    banned verbs with "run" as the replacement, which has no noun form. Needs a
    ruling on whether the noun is covered.
  5. Twenty historical release-notes entries describe the product as the "Windows
    LSAM". Whether published history is reworded to current terminology is a policy
    decision, so they are unchanged.

🤖 Generated with Claude Code

…dardize terminology and links

Release notes

- Every one of the 88 entries carried the enhancement marker and none carried
  the bug-fix marker, so a reader could not tell a new feature from a fix. The
  page's own description promises "new features, improvements, and bug fixes",
  and the page already groups many entries under Fixes headings; the markers
  contradicted the structure they sat in.
- 64 entries now carry the bug-fix marker: every entry under a Fixes heading,
  plus eight corrective entries in 20.2.0 to 20.4.0 that have no sub-heading
  and open with "Fixed an issue". Two entries that read as updates are marked
  as fixes because they are filed under Fixes, following the page's existing
  classification rather than reclassifying them. The other 24 entries are
  features and keep the enhancement marker.
- Added the legend used by the core OpCon release notes, so the two markers
  are explained on the page.

Terminology

- Replaced seven verb forms of "execute" with "run", including the landing
  page's description of what the agent does. "Execute rights", the name of a
  Windows file permission, is left as it is, as is "executable" as a noun.

Examples

- The AllowedIPAddress example used 126.40.90.231, a routable address in an
  allocated block. Changed to 192.0.2.10, from a range reserved for
  documentation so that an example cannot point at a live host.

Links

- Relative links were split between two styles, 29 with the .md extension and
  33 without. All 62 now use the .md form. Every link resolved before and
  after the change; there are no dead links or broken anchors on the site.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rweesner
rweesner requested a review from a team as a code owner September 24, 2026 15:56
Five instances of UI terms the documentation standards replace, missed by the
first pass:

- "dialog box" and "dialog" become "window", in the service configuration and
  installation procedures.
- "Select the Services icon" becomes "Select Services", in both places it
  appears in the upgrade procedure. The standards drop "icon" and refer to the
  item by name.
- "the process cannot be launched" becomes "cannot be started", in the
  machine messages reference.

No change of meaning. Links and anchors are unaffected and the site builds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rweesner rweesner self-assigned this Oct 2, 2026
@rweesner
rweesner requested a review from MoKranda October 2, 2026 21:07
@MoKranda
MoKranda merged commit 5209b5b into main Oct 5, 2026
1 check passed
@MoKranda
MoKranda deleted the docs/release-notes-markers-and-terminology branch October 5, 2026 15:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants