---
name: technical-writing
description: Write task-oriented developer documentation and Dev Portal page copy in plain, active-voice prose with clear, scannable structure. Use when authoring or editing technical docs, API guides, and page content.
license: MIT
metadata:
  product: konnect
  category: documentation
  tags:
    - kong
    - konnect
    - dev-portal
    - documentation
    - api-documentation
    - writing
---

# Technical documentation writing

## Goal

Write and edit developer-facing documentation that is easy to consume: plain,
task-oriented, active-voice prose with scannable structure and clean punctuation.
Own the words and their organization within a page.

Not Dev Portal specific, but it pairs with the portal skills: `portal-page-design`
for the components that hold the prose, `portal-branding` for appearance. Work in
page content files, locally or in a repo, and do not push destructive changes to a
live portal unless the user explicitly asks.

## Clarify First

Ask two or three high-impact questions, each with a default to confirm:

- the reader and the task the page serves
- the source of truth for the technical details
- an existing page to match in tone and structure, if any
- the depth expected, from quickstart to full reference

## Tool Selection

- Documenting Konnect resources: pull real details (control planes, services,
  routes, specs) from real entities through the `kong-konnect` MCP server instead
  of inventing values. If it is not connected, recommend installing it; otherwise
  ask the user for real values or mark them clearly as placeholders, not guesses.
- Portal-page content: hand structure and components to `portal-page-design` and
  keep this skill on the prose.
- Follow Kong's documentation style guide for terminology and capitalization on
  Kong content; default to the Google and Microsoft developer style guides
  otherwise.
- Unsure of Kong terminology or how Kong documents a concept: check the server's
  Kong documentation knowledge base. If unavailable, rely on the style guides and
  flag anything you cannot confirm.

## Workflow

1. Name the reader and the task; lead with what the reader does.
2. Choose the structure from that task and keep one use case on one page.
3. Write in the house voice: second person, active voice, present tense, plain,
   front-loaded, scannable. Recommend choices with a reason.
4. Make it self-contained: real values from MCP or the user, placeholders for
   reader-supplied values, one command per block, a verification step to close a
   how-to.
5. Edit out the tells as a final pass.
6. Match the density: cut a sentence that repeats the previous one; add one the
   reader would otherwise guess.

## Style rules

These combine Kong's documentation style guide with the Google and Microsoft
developer style guides, which agree on the core.

Voice and grammar:

- Second person, active voice, present tense. Passive voice hides who acts; name
  the actor.
- Plain verbs: "run" not "execute," "use" not "utilize," "to" not "in order to."
- Contractions are fine in prose; drop them in warnings for a serious tone.
- Name what a bare "this" points to. No Latin abbreviations (use "for example,"
  "that is"). Use allowlist and denylist, main branch, and neutral pronouns.
- Recommend with "we recommend" and always give the reason.

Headings, lists, tables:

- Headings: descriptive, not generic; sentence case; task headings can use a bare
  verb.
- Numbered lists for sequences, bulleted otherwise; parallel structure; end
  punctuation only for full sentences.
- Tables for parameter references, status codes, and comparisons.

Code samples:

- One command per block; commands and output in separate blocks; language-tag
  every block; no `$` prompt; wrap long commands with `\`.
- Placeholders: `ALL_CAPS_WITH_UNDERSCORES` for generic values, `{curlyBraces}`
  for spec parameters, `example.com` for illustration, `localhost` for runnable
  examples. Never embed real secrets.

Kong terminology:

- Capitalize Gateway entities: Certificate, Consumer, Plugin, Route, Service,
  Target, Upstream, Vault.
- Keep lowercase: control plane, data plane, application, developer, hybrid mode,
  service mesh.
- Plugin names: capitalize the name, not "plugin" ("Rate Limiting plugin"); use
  the lowercase slug in code (`rate-limiting`).
- American English. Refer to third-party UI by label only, not color or position.

Page tenets:

- Every page is page one: a reader answers their question on one page; do not split
  a concept from its configuration.
- A how-to has validation: the final step confirms the product works.

## Avoid LLM tells

These patterns make prose read as machine-generated. Remove them in a final
editing pass, in this order (em-dashes and en-dashes are the clearest tell, so
start there):

1. Delete every em-dash and en-dash, rewriting the sentence around it. The hard cap
   is zero, headings included. Replace with a comma, colon, parentheses, or two
   sentences, and do not use `--` as a substitute.
2. Replace always-replace words: delve to explore; leverage (verb) to use; robust
   to reliable; seamless to smooth; utilize to use; landscape (metaphor) to field.
   For tapestry, synergy, game-changer, cutting-edge, and embrace (metaphor), say
   the concrete thing.
3. Cut hedges, intensifiers, and template openers (see below).
4. Break up any run of three same-length sentences.

Constructions to avoid:

- "It's not just X, it's Y" and "not only X but Y." Rewrite as a direct statement,
  at most one per document.
- Hollow hedges and intensifiers: genuinely, truly, quite frankly, it's worth
  noting that, it's important to note, could potentially. Keep one hedge at most.
- Vague endorsements ("worth reading"), chatbot artifacts ("Great question!", "I
  hope this helps!"), and template openers ("In today's X," "When it comes to,"
  "Whether you're X or Y").
- Cutoff disclaimers and unfilled placeholders left in the text.

Flag-in-clusters words: any one may be fine, but if two or more cluster, rewrite
the paragraph plainly: harness, navigate, foster, elevate, unleash, streamline,
empower, bolster, resonate, revolutionize, facilitate, underpin, ecosystem,
myriad, plethora.

Rhythm: prefer plain copulas ("is," "has") over "serves as," "boasts," "features."
Do not synonym-cycle; repeat the clearest term. Vary sentence length; machine prose
is metronomic.

## Documentation structures

Pick the shape from the reader's task, then write each section in the house voice.
On a Dev Portal, hand components and layout to `portal-page-design`; this covers
what each section says and in what order.

Page types:

- Landing page: signpost the reader to the right next page. State value in one or
  two lines, then link. Do not teach here.
- How-to: an end-to-end task that ends with a validation step.
- Reference: concepts plus tables and schemas, with everything for one use case
  kept together.

API or product page, a dependable order:

- Hero: what the product does and who it is for, in one or two lines, plus the
  primary next step. Front-load value.
- Getting started: the shortest path to a first success. List every prerequisite
  up front, give copy-paste steps, and end with a step that proves it worked.
- Authentication: early and self-contained. Show how to obtain and send credentials
  with placeholders. Never show a real secret.
- Request and response samples: put request and response in separate,
  language-tagged blocks (formatting under Code samples).
- Troubleshooting or FAQ: headings phrased as the reader's actual question, with
  the cause and the fix in that order.

When documenting Konnect resources, pull real values from the `kong-konnect` MCP
server or the user's config; concrete examples beat invented ones, and keep secrets
out.

Keep each section self-contained and no longer than it needs to be.

## Validation Checklist

- reader and task identified
- leads with the task; one use case per page
- second person, active voice, present tense, scannable
- placeholders in samples; how-to ends with verification
- no em-dashes, banned filler, or template openers
- real values from MCP or the user, not invention

## Handoffs

- `portal-page-design` for the components and layout that present this content.
- `portal-branding` when the request is about appearance rather than wording.
- `konnect-api-publish` or `konnect-api-catalog` when the real gap is that an API is
  not published or modeled, not that its docs need writing.