Repository navigation
docs: mark release-notes bug fixes as bug fixes, add the legend, standardize terminology and links - #94
Merged
Conversation
…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>
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>
MoKranda
approved these changes
Oct 5, 2026
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
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.
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
.mdform.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.
eight corrective entries in 20.2.0–20.4.0 that have no sub-heading and open with
"Fixed an issue".
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.
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_1example used126.40.90.231, a routable address in anallocated 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
.mdextension and 33without. All 62 now use the
.mdform. Every link resolved before and after thechange.
Verification
.mdform.Follow-ups for an owner
Not changed here, each needing a decision rather than an edit:
onBrokenAnchorsis unset, so it defaults towarn, whileonBrokenLinksisset to
throw. This site currently has zero broken anchors, so setting it tothrowwould cost nothing today and would stop regressions. Not changed herebecause it alters build behavior for every contributor.
administration/manage-lsam.mdputs the legacy term in a published URL. Everyvisible 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.iniand theSMA_MSLSAM_*variables, or the LSAM Feedback category,which is a UI label and must match the product.)
"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.
banned verbs with "run" as the replacement, which has no noun form. Needs a
ruling on whether the noun is covered.
LSAM". Whether published history is reworded to current terminology is a policy
decision, so they are unchanged.
🤖 Generated with Claude Code