Skip to content

docs: fix the socket example, procedure structure, terminology, front matter and links - #95

Merged
MoKranda merged 1 commit into
mainfrom
docs/consistency-and-standards
Sep 25, 2026
Merged

MoKranda merged 1 commit into
mainfrom
docs/consistency-and-standards

Conversation

@rweesner

Copy link
Copy Markdown
Contributor

Fixes a socket-number example that contradicted the configuration reference, restructures
the machine-creation procedure, brings terminology and front matter in line with the
documentation standards, and adds the release-notes legend.

6 files, one commit. No product behavior is described here that the pages did not already
state.

Installation

  • Socket number example. The machine-creation procedure gave 3100 as the example.
    The configuration page says the Java Agent's SocketNumberToSAM defaults to 17100
    and that the machine's socket number must match it — so following the example produced
    a machine the agent would not talk to. The step now says the value must match
    SocketNumberToSAM, which defaults to 17100.
  • Procedure structure. The three parts of the procedure were bold "Step 1 / Step 2 /
    Step 3" labels with no lead-in. They are now headings, each with a "To …, complete the
    following steps:" lead-in.
  • Standards. Optional steps start with "(Optional)"; menu paths bold each label rather
    than the whole path; installer wizard pages are "steps" and dialogs are "windows".

Configuration file

  • The allowed-address example used a routable address; now 192.0.2.10, from a range
    reserved for documentation.
  • Two references to Enterprise Manager "screens" are reworded.

Landing page

Added title, description and tags front matter in the same shape as the other agent
sites. The link menu is unchanged.

Release notes

Added the marker legend used by the core OpCon release notes. The markers are unchanged —
they match the page as the release authors left it.

Links

The two relative links without the .md extension now use it.

Follow-ups for an owner

These need someone who knows the product; the pages cannot settle them.

  1. JORS socket default. The configuration table gives JORSSocket a default of
    18110; the example Agent.config on the same page sets 17110.
  2. Section name. The table calls the section [Application Connector Settings]; the
    example calls it [Application Connection Settings]. If the agent matches section
    names, one of these is ignored. LibrariesDirectory also appears as Libraries in the
    table and libraries in the example.
  3. Undocumented features. The release notes describe the JAR operation (16.1.0)
    and the Alternate JVM field, JVM Arguments and Environment Variables tabs,
    and JAVA_ENV_VARS / JAVA_JVM_ARGS (17.0.0), but no page documents them. The
    overview lists three operation types while the machine-messages page describes
    anything other than Class or Command as invalid.
  4. "Right-select" in the Start communication step. The standards ban both "click" and
    "right-select" without giving an approved wording — open across all agent sites.
  5. Requirements. .NET Framework 4.0 is out of support; the current requirement needs
    confirming.

Verification

  • 0 front-matter gaps, 0 dead links, 0 broken anchors, 0 orphan pages.
  • Every numbered procedure has a lead-in; all 17 relative links use .md.
  • The site builds.

🤖 Generated with Claude Code

… matter and links

Installation

- The machine-creation procedure gave 3100 as the example socket number.
  The configuration page says the Java Agent's SocketNumberToSAM defaults to
  17100 and that the machine's socket number must match it, so a reader
  following the example created a machine the agent would not talk to. The
  step now says the value must match SocketNumberToSAM, which defaults to
  17100.
- The procedure's three parts were bold "Step 1", "Step 2" and "Step 3"
  labels with no lead-in sentences. They are now headings, each with a
  "To ..., complete the following steps:" lead-in.
- Optional steps now start with "(Optional)", and menu paths bold each label
  rather than the whole path.
- Installer wizard pages are referred to as steps and dialogs as windows,
  as the documentation standards require.

Configuration file

- The allowed-address example used a routable address; changed to
  192.0.2.10, from a range reserved for documentation.
- Two references to Enterprise Manager screens are reworded.

Landing page

- Added title, description and tags front matter, in the same shape as the
  other agent sites. The link menu is unchanged.

Release notes

- Added the marker legend used by the core OpCon release notes. The markers
  themselves are unchanged: they match the page as the release authors left
  it.

Links

- The two relative links without the .md extension now use it.

Not changed here, because the pages cannot settle them: the JORS socket
default (18110 in the table, 17110 in the example) and the Application
Connector/Connection section name disagree within the configuration page,
and the JAR operation and the 17.0.0 job-definition features appear only in
the release notes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@rweesner
rweesner requested a review from a team as a code owner September 25, 2026 13:37
@MoKranda
MoKranda merged commit 125173f into main Sep 25, 2026
1 check passed
@MoKranda
MoKranda deleted the docs/consistency-and-standards branch September 25, 2026 16:31
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