Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

technical-writing

Write or review reference prose in the house register — markdown documents, wiki pages, README and CONTRIBUTING text, and configuration comments. USE FOR: explaining a contract, a behavior, a decision, or an API in human-readable text, and reviewing that a text says something a reader cannot already infer. DO NOT USE FOR: comments inside source code and documentation comments on an API, both of which follow the conventions of the language; or the body of an issue, a pull request, or a comment on one, whose shape and register the workflow standard states.

Nice3point · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add Nice3point/revit-skills --skill technical-writing

About this skill


name: technical-writing description: > Write or review reference prose in the house register — markdown documents, wiki pages, README and CONTRIBUTING text, and configuration comments. USE FOR: explaining a contract, a behavior, a decision, or an API in human-readable text, and reviewing that a text says something a reader cannot already infer. DO NOT USE FOR: comments inside source code and documentation comments on an API, both of which follow the conventions of the language; or the body of an issue, a pull request, or a comment on one, whose shape and register the workflow standard states. license: MIT

Technical Writing

Write to an enterprise production standard in a strict technical register, never a tutorial or a marketing voice. Open with the fact the reader needs, describe observable behavior, and cut anything a reader can already infer. Every reference text follows this standard: a wiki page, a README, a CONTRIBUTING guide, and a comment inside a configuration file. The standard follows the Microsoft Writing Style Guide: lead with the fact, write short paragraphs, favor the active voice and the serial comma, capitalize a heading in sentence case, spell out a Latin abbreviation in full, and name a person without gender. The register is third person. A stranger reads a reference page, and the page never addresses the reader as "you".

When to use

  • Writing or reviewing reference markdown in a repository.
  • Reviewing a text that reads as a narration of the change instead of a statement of the result.
  • Writing or reviewing a comment that annotates a declaration, a key, or a block of a configuration file.

Rules

  • Use plain technical English and the third-person present indicative in reference prose.
  • Write in the active voice: the subject performs the action, and a value is never acted upon by an unnamed actor.
  • Write one sentence per line, with one idea per sentence.
  • Ignore the line length; a sentence occupies one line however long it runs, and no line is wrapped by hand. The IDE reflows the file to the limits configured for it.
  • Place a comma before the conjunction in a list of three or more items.
  • Spell out for example, that is, and and so on; never e.g., i.e., or etc..
  • Name a person, a role, or an audience without gender, and without an idiom tied to one culture.
  • Use a heading that names its subject, with a colon where the heading introduces a variant or a qualifier. Capitalize it in sentence case, its first word and any proper noun alone, except a section a template fixes or a title matching its file's name.
  • Use a list only where the reader acts on, compares, or remembers several items.
  • Use a table where several items share the same set of attributes.
  • State a negative only where a competent reader would otherwise make a plausible, harmful assumption.
  • Link the maintained list of identifiers, endpoints, or values; never copy it.
  • State no count and no enumeration the neighbouring source already lists: the rows of a table, the members of an adjoining list, the files of a directory. The reader reads them in the source, and a restatement becomes outdated when an item is added.
  • Avoid corporate language, filler, meta-preambles, and trailing including… examples.
  • Comment the intent, the constraint, or the invariant a file cannot state itself; add none where the file already states it. The name of a declaration states its meaning, and a comment is added only where a competent reader draws a wrong conclusion without one. A comment never restates the name, the value, or the block below it.
  • Judge every sentence as final standalone text. The reader has the page as it stands, with no previous version, diff, or request to compare against.
  • Cut every purpose, result, cause, and comparison clause: so, that makes, which makes, because, rather than. A clause that states a fact the reader needs becomes its own sentence.
  • Name every operation with the term its own domain defines. A component requests, returns, requires, reports, or selects; a value is passed or assigned; a subscriber receives an event; a person is notified.
  • Name every relation with the verb specific to its subject. A text states, lists, defines, or describes; a file contains or stores; a type declares or exposes; a method returns; a rule applies to its scope.

Examples

<!-- BAD -->
This page describes external events. We added them because the API is not reachable from a modeless window, which makes a direct call fragile, so a queue was introduced to solve the problem.

<!-- GOOD -->
An external event executes a unit of work in the Revit API context.
A caller constructs the event and raises it from any thread, and Revit invokes the handler inside the API context.
An external event opens no transaction; the handler opens its own.
<!-- BAD -->
The view model asks the repository for the open document and answers the command with the result.
The binding wants a source that is not null, and the validator decides whether the entry is valid.
An event travels to every subscriber.

<!-- GOOD -->
The view model requests the open document from the repository and returns the result to the command.
The binding requires a source that is not null, and the validator reports whether the entry is valid.
Every subscriber receives the event.

A comment on a declaration names the role of that declaration in the system, or the invariant behind a value.

# BAD
# The catalogue viewer, a second process of the frontend group on a port of its own, declared in this same file.
# The internal gateway alone carries this route, and every public gateway resolves the frontend on its plain port, so no public host reaches it.
component "catalogue" {

# GOOD
# The gateway of the public applications and of the internal-only endpoints.
component "gateway" {

# GOOD
# The cache every service of the environment shares.
compone
Read the complete source ↗