<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Gabe Garcia</title>
    <description>The latest articles on DEV Community by Gabe Garcia (@gabegarcia_rephrase).</description>
    <link>https://dev.to/gabegarcia_rephrase</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4199006%2F0951e529-4c6f-47a0-9566-5edea213d81f.png</url>
      <title>DEV Community: Gabe Garcia</title>
      <link>https://dev.to/gabegarcia_rephrase</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/gabegarcia_rephrase"/>
    <language>en</language>
    <item>
      <title>Another way to say ensure in code reviews, docs and PR descriptions</title>
      <dc:creator>Gabe Garcia</dc:creator>
      <pubDate>Mon, 02 Nov 2026 18:48:54 +0000</pubDate>
      <link>https://dev.to/gabegarcia_rephrase/another-way-to-say-ensure-in-code-reviews-docs-and-pr-descriptions-4985</link>
      <guid>https://dev.to/gabegarcia_rephrase/another-way-to-say-ensure-in-code-reviews-docs-and-pr-descriptions-4985</guid>
      <description>&lt;h1&gt;
  
  
  Ensure alternatives for developers, sorted by what the sentence is really saying
&lt;/h1&gt;

&lt;p&gt;Read ten pull request descriptions and most of them will use ensure. "Ensure the cache is cleared." "This PR ensures backwards compatibility." "Please ensure tests pass." It sounds careful. Often it hides what the change does.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why ensure creeps into every PR
&lt;/h2&gt;

&lt;p&gt;Ensure is a safe verb. It sounds responsible and fits almost anywhere, which is exactly the problem. One word can mean the code checks something, a person should check something, the code guarantees something, or a change exists for a reason. The reader has to guess which.&lt;/p&gt;

&lt;p&gt;That guess matters in a review. "This ensures the user is logged in" could mean there is a middleware check, a redirect, a test, or just a hope. A reviewer who reads it as a guarantee may skip the line that needs the most attention.&lt;/p&gt;

&lt;p&gt;The fix is to pick the verb that matches what actually happens.&lt;/p&gt;

&lt;h2&gt;
  
  
  Alternatives grouped by meaning
&lt;/h2&gt;

&lt;h3&gt;
  
  
  The code checks or rejects something
&lt;/h3&gt;

&lt;p&gt;Use &lt;strong&gt;validates&lt;/strong&gt;, &lt;strong&gt;checks&lt;/strong&gt;, &lt;strong&gt;rejects&lt;/strong&gt;, &lt;strong&gt;returns early&lt;/strong&gt; or &lt;strong&gt;throws&lt;/strong&gt;. These tell the reader where the check lives and what happens on failure.&lt;/p&gt;

&lt;p&gt;"The handler rejects requests without a token" says more than "ensures requests have a token".&lt;/p&gt;

&lt;h3&gt;
  
  
  A person should do something
&lt;/h3&gt;

&lt;p&gt;Use &lt;strong&gt;make sure&lt;/strong&gt;, &lt;strong&gt;check&lt;/strong&gt;, &lt;strong&gt;confirm&lt;/strong&gt; or &lt;strong&gt;remember to&lt;/strong&gt;. In review comments, a direct question usually works better than an order.&lt;/p&gt;

&lt;p&gt;"Can you confirm this runs after the migration?" invites an answer. "Ensure this runs after the migration" invites a thumbs up.&lt;/p&gt;

&lt;h3&gt;
  
  
  The code really guarantees it
&lt;/h3&gt;

&lt;p&gt;Use &lt;strong&gt;guarantees&lt;/strong&gt;, &lt;strong&gt;prevents&lt;/strong&gt; or &lt;strong&gt;always&lt;/strong&gt;. Save these for things that hold under every path, and be ready to point at the reason.&lt;/p&gt;

&lt;p&gt;"The lock prevents two workers from picking up the same job."&lt;/p&gt;

&lt;h3&gt;
  
  
  The change exists for a reason
&lt;/h3&gt;

&lt;p&gt;Use &lt;strong&gt;so that&lt;/strong&gt;, &lt;strong&gt;to&lt;/strong&gt; or &lt;strong&gt;which means&lt;/strong&gt;. This is the most common hidden meaning, and the easiest to fix.&lt;/p&gt;

&lt;p&gt;"Sort the keys so that the output is stable between runs."&lt;/p&gt;

&lt;h3&gt;
  
  
  A test covers it
&lt;/h3&gt;

&lt;p&gt;Use &lt;strong&gt;covers&lt;/strong&gt;, &lt;strong&gt;asserts&lt;/strong&gt; or &lt;strong&gt;adds a test for&lt;/strong&gt;. Reviewers like knowing exactly which case is pinned down.&lt;/p&gt;

&lt;p&gt;"Adds a test that covers empty input and a single item."&lt;/p&gt;

&lt;h2&gt;
  
  
  Review comments rewritten
&lt;/h2&gt;

&lt;p&gt;Vague review comments slow everyone down. The author has to work out what you saw, then guess what you want.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Before   Please ensure this is handled.
After    What happens here if user is null? An early return might help.

Before   Ensure naming is consistent.
After    Other handlers use fetchX. Could we rename loadUser to fetchUser?

Before   We should ensure we don't break existing clients.
After    Older clients still send the v1 field. Can we keep reading it
         until the v2 rollout is done?
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each rewrite names the case, the evidence, or the next step. None of them is longer by much.&lt;/p&gt;

&lt;h2&gt;
  
  
  PR descriptions and README lines rewritten
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Before   This PR ensures that the retry logic works properly.
After    Retries now back off exponentially and stop after five attempts.
         Adds tests for the timeout and success paths.

Before   Ensure that you have Node 20 installed.
After    Install Node 20 or later before running the setup script.

Before   This change ensures data integrity.
After    Writes now run in a single transaction, so a failed step rolls
         back the whole update.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The last one is the most useful pattern. "Data integrity" was a label. The rewrite explains the mechanism, which is what a future reader digging through git blame wants to find.&lt;/p&gt;

&lt;h2&gt;
  
  
  When only the verb is missing
&lt;/h2&gt;

&lt;p&gt;Sometimes you know the meaning and the exact word won't come. Say the code stops a bad value at the door, and validates feels too broad for the comment. In that spot, Rephrase AI's word rephraser lets you &lt;a href="https://www.rephraseai.com/tools/word-rephraser" rel="noopener noreferrer"&gt;find a better word&lt;/a&gt; without rewriting the line. Paste ensure, or any phrase of 40 characters or fewer, pick one of the Clearer, Professional and Shorter styles, and it returns between five and eight options.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fmwzdh3lklmc8vnzqupe4.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fmwzdh3lklmc8vnzqupe4.png" alt="Rephrase AI Word Rephraser page with the Clearer style selected, the word ensure in the Word or short phrase box, and eight alternatives including guarantee, confirm, verify and make certain."&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The lone verb ensure typed into Rephrase AI's word rephraser, Clearer style selected.&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Before   This function ensures the input is valid.
After    This function rejects input that fails the schema.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The tool gives you options. You still pick the one that matches what the code does, then finish the sentence.&lt;/p&gt;

&lt;h2&gt;
  
  
  A quick pass before you request review
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Search your PR description and any changed docs for ensure.&lt;/li&gt;
&lt;li&gt;For each one, decide which of the five meanings it carries.&lt;/li&gt;
&lt;li&gt;If it is a guarantee, point to the test or the code that backs it.&lt;/li&gt;
&lt;li&gt;If it is an instruction, consider turning it into a question or a checklist item.&lt;/li&gt;
&lt;li&gt;If it is a reason, rewrite it with so that.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The whole pass is short, and reviewers notice. Clear verbs lead to shorter review threads, because fewer comments start with "what do you mean by".&lt;/p&gt;

&lt;p&gt;For a description that still drags after these swaps, give the whole thing to &lt;a href="https://rephraseai.com" rel="noopener noreferrer"&gt;Rephrase AI&lt;/a&gt; on Shorter, then keep whichever wording leaves your reviewer with no questions.&lt;/p&gt;

</description>
      <category>writing</category>
      <category>codereview</category>
      <category>documentation</category>
      <category>productivity</category>
    </item>
    <item>
      <title>Technical writing examples for definitions, warnings, config docs and code comments</title>
      <dc:creator>Gabe Garcia</dc:creator>
      <pubDate>Thu, 29 Oct 2026 18:29:36 +0000</pubDate>
      <link>https://dev.to/gabegarcia_rephrase/technical-writing-examples-for-definitions-warnings-config-docs-and-code-comments-38dd</link>
      <guid>https://dev.to/gabegarcia_rephrase/technical-writing-examples-for-definitions-warnings-config-docs-and-code-comments-38dd</guid>
      <description>&lt;p&gt;Technical writing isn't only long manuals. Most of it is small. A one line definition in a glossary. A warning box above a dangerous command. A description beside a config option. A comment above a tricky loop. These bits get read at the exact moment someone is about to make a mistake, so the wording matters more than its length suggests.&lt;/p&gt;

&lt;p&gt;This post collects annotated technical writing examples from the small places in docs and code. Each one shows a weak version, a stronger version and the reason the stronger one works. I've left out READMEs, error messages and endpoint reference pages, since those have their own guides.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. A definition
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Weak.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;A tenant is a logical isolation boundary within the multi-tenant architecture.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Strong.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;A tenant is one customer's space in the app. Each tenant has its own users, data and settings, and nothing in one tenant is visible from another.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The weak version defines the word with harder words. The strong one says what it is, what it contains and the rule that matters. Good definitions answer "what is it" and "why do I care" in two sentences.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. A warning
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Weak.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Note. Be careful when running this command.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Strong.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Warning. &lt;code&gt;db reset&lt;/code&gt; deletes every table in the target database. Run it against staging only, and check the &lt;code&gt;DATABASE_URL&lt;/code&gt; value first.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;"Be careful" gives the reader nothing to be careful about. A warning should name the consequence, the safe case and one concrete check. If you can't name the consequence, it probably isn't a warning.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. A config option
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Weak.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Option&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;max_retries&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Max retries.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Strong.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Option&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;max_retries&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;How many times a failed job is retried before it moves to the dead letter queue. Default 3. Set to 0 to disable retries.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A description that repeats the option name is a missed chance. Say what it controls, the default and what the edge values do.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. A code comment
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Weak.&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="c1"&gt;# loop through items
&lt;/span&gt;&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="ow"&gt;in&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;qty&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="ow"&gt;and&lt;/span&gt; &lt;span class="ow"&gt;not&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;hold&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="nf"&gt;ship&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Strong.&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="c1"&gt;# Items on hold are waiting for a fraud review, so we skip them
# even when they're in stock. They ship in the nightly batch instead.
&lt;/span&gt;&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="ow"&gt;in&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;qty&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="ow"&gt;and&lt;/span&gt; &lt;span class="ow"&gt;not&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;hold&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="nf"&gt;ship&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The code already says what it does. A comment should say why, especially when the why lives in another team's head.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. A concept overview
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Weak.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;The system leverages an event-driven paradigm wherein state transitions are propagated asynchronously via a message broker to downstream consumers.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Strong.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;When an order changes status, the order service publishes an event. Other services, like billing and email, listen for those events and react on their own schedule. The order service doesn't wait for them.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Swap abstract nouns for actors and actions. "Leverages an event-driven paradigm" becomes "publishes an event," and the reader can picture it.&lt;/p&gt;

&lt;p&gt;Concept paragraphs are where most rewording happens. The facts are right, the order is wrong, and the vocabulary is borrowed from a whiteboard. Learning to &lt;a href="https://www.rephraseai.com/blog/how-to-reword-a-paragraph-without-losing-meaning" rel="noopener noreferrer"&gt;reword a paragraph and keep its meaning&lt;/a&gt; is the core skill here, because a clearer version that drops a fact is worse than the dense one.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. A migration note
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Weak.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Version 4 introduces breaking changes to the auth module. Please update accordingly.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Strong.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Version 4 renames &lt;code&gt;login()&lt;/code&gt; to &lt;code&gt;signIn()&lt;/code&gt; and removes the &lt;code&gt;remember&lt;/code&gt; flag. To upgrade, rename the call and move &lt;code&gt;remember&lt;/code&gt; to the session options. Apps that skip this step will fail to compile.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;"Update accordingly" pushes all the work onto the reader. The strong version lists what changed, what to do and what happens if they don't.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. A troubleshooting entry
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Weak.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;If sync isn't working, try restarting.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Strong.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Sync shows "pending" for more than ten minutes.&lt;/strong&gt; This usually means the device token expired. Sign out and back in on that device. If it still shows pending, send us the sync ID from Settings and we'll check the server side.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;A troubleshooting entry needs a symptom as the heading, a likely cause, one fix and a next step if the fix fails.&lt;/p&gt;

&lt;h2&gt;
  
  
  Patterns across all seven
&lt;/h2&gt;

&lt;p&gt;Looking at them together, the same moves keep showing up.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Name the thing.&lt;/strong&gt; Commands, options, values and versions by their real names.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;State the consequence.&lt;/strong&gt; What happens if the reader does or doesn't act.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Prefer actors and verbs.&lt;/strong&gt; "The service publishes" beats "publication occurs."&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Give one next step.&lt;/strong&gt; A reader who finishes a passage should know what to do.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep the facts fixed.&lt;/strong&gt; Rewording changes sentences, never defaults, limits or names.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Practicing on your own docs
&lt;/h2&gt;

&lt;p&gt;Pick one page and look only at its definitions and warnings. They're short, so you can fix a dozen in an afternoon. Then move to concept paragraphs, which take longer but pay off most.&lt;/p&gt;

&lt;p&gt;If a concept paragraph keeps defeating you, put it through &lt;a href="https://rephraseai.com" rel="noopener noreferrer"&gt;Rephrase AI&lt;/a&gt; and read the alternative aloud next to your draft, while you hold every option name, version number and default value fixed as the spec says.&lt;/p&gt;

</description>
      <category>writing</category>
      <category>documentation</category>
      <category>beginners</category>
      <category>programming</category>
    </item>
    <item>
      <title>Jira ticket template that saves a back-and-forth</title>
      <dc:creator>Gabe Garcia</dc:creator>
      <pubDate>Thu, 29 Oct 2026 18:29:07 +0000</pubDate>
      <link>https://dev.to/gabegarcia_rephrase/jira-ticket-template-that-saves-a-back-and-forth-14hh</link>
      <guid>https://dev.to/gabegarcia_rephrase/jira-ticket-template-that-saves-a-back-and-forth-14hh</guid>
      <description>&lt;p&gt;Every vague ticket costs a conversation. Someone grabs it from the board, reads "Fix login," and has to ping the person who filed it. That person is on vacation. The ticket sits.&lt;/p&gt;

&lt;p&gt;A good Jira ticket answers the questions a stranger would ask before they start. This post covers a title formula, three short description templates for stories, bugs and tasks, and unclear tickets rewritten into ones a teammate could pick up on a Monday morning without asking anybody.&lt;/p&gt;

&lt;p&gt;It focuses on the ticket itself, meaning the title and the description field. If you want deeper help with the story format or with testable criteria, those deserve their own guides.&lt;/p&gt;

&lt;h2&gt;
  
  
  Start with the title
&lt;/h2&gt;

&lt;p&gt;The title shows up on the board, in sprint planning, in Slack previews and in release notes. Most people never open the ticket. So the title has to stand alone.&lt;/p&gt;

&lt;p&gt;A formula that works is &lt;strong&gt;area, then what changes, then for whom or when.&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;"Billing, show tax line on invoice PDF for EU customers"&lt;/li&gt;
&lt;li&gt;"Search, keep filters after the user presses Back"&lt;/li&gt;
&lt;li&gt;"CI, cache npm install on the main pipeline"&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Lead with the area so the board sorts nicely. Use a verb so it reads as work. Leave out words like "issue," "problem" and "investigate" unless investigating is the whole job.&lt;/p&gt;

&lt;h2&gt;
  
  
  Three description templates
&lt;/h2&gt;

&lt;p&gt;Paste these into Jira as description templates or keep them in a snippet tool. They use Jira's markdown style headings, so they render cleanly.&lt;/p&gt;

&lt;h3&gt;
  
  
  Story
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;h3. Context
Who needs this and what they do today.

h3. Change
What should be different when this is done.

h3. Out of scope
What this ticket does not cover.

h3. Links
Design, related tickets, Slack thread.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Bug
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;h3. What happened
One sentence. Include the environment.

h3. Expected
What should have happened.

h3. Steps to reproduce
1.
2.

h3. Evidence
Screenshot, log line, request ID.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Task or spike
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;h3. Goal
The question to answer or the chore to finish.

h3. Done when
A concrete output, like a doc, a PR or a decision.

h3. Timebox
For spikes, the most time to spend before reporting back.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The spike template matters more than it looks. Without a "done when" line and a timebox, research tickets drift for a full sprint and close with "looked into it."&lt;/p&gt;

&lt;h2&gt;
  
  
  Unclear tickets, rewritten
&lt;/h2&gt;

&lt;p&gt;These are typical board tickets with names changed.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Unclear title.&lt;/strong&gt; "Login broken"&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewritten title.&lt;/strong&gt; "Auth, Google sign in fails on Safari 17 with a blank popup"&lt;/p&gt;

&lt;p&gt;The first could mean anything. The second tells you the provider, the browser and the symptom, so the right engineer picks it up.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Unclear description.&lt;/strong&gt; "Customers are complaining about exports. Please look into this ASAP."&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewritten description.&lt;/strong&gt; "Three support tickets this week say CSV exports from the Reports page stop at 5,000 rows. Larger accounts need all rows. Expected result is a full export or a clear message that it's been split into parts. Ticket links are below."&lt;/p&gt;

&lt;p&gt;The rewrite turns a feeling into a count, a place, a limit and an expected outcome.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Unclear task.&lt;/strong&gt; "Update the docs"&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewritten task.&lt;/strong&gt; "Docs, add the new rate limit headers to the API reference page. Done when the page lists all three headers with an example response."&lt;/p&gt;

&lt;p&gt;Now it has a scope and a finish line.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Unclear spike.&lt;/strong&gt; "Research caching options"&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewritten spike.&lt;/strong&gt; "Spike, compare Redis and in-process caching for the pricing endpoint. Done when there's a one page comparison with latency numbers from staging. Timebox two days."&lt;/p&gt;

&lt;p&gt;Most of these fixes happen at the sentence level. The facts stay put while the order shifts, so the reader meets the point first. If you want more practice, there's a set of &lt;a href="https://www.rephraseai.com/blog/rephrase-my-sentence-examples" rel="noopener noreferrer"&gt;sentence rewrites for unclear tickets&lt;/a&gt; and other everyday writing that shows the same moves.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fields that do more than the text
&lt;/h2&gt;

&lt;p&gt;The description isn't the only place clarity lives.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Priority.&lt;/strong&gt; Pick based on impact, not on who asked loudest.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Labels.&lt;/strong&gt; Use a short shared list. Ten labels that mean the same thing help nobody.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Linked issues.&lt;/strong&gt; Link the blocker instead of writing "blocked by the other ticket."&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Assignee.&lt;/strong&gt; Leave it empty if nobody owns it yet. A fake owner hides the work.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  A quick check before you file
&lt;/h2&gt;

&lt;p&gt;Read the ticket as if you joined the team yesterday. Can you tell what to change, where, and how you'd know it's finished? If not, add the missing line now. It takes a minute, and it saves a message thread later.&lt;/p&gt;

&lt;p&gt;When the description is right but still reads like a hurried note, paste that block into &lt;a href="https://rephraseai.com" rel="noopener noreferrer"&gt;Rephrase AI&lt;/a&gt; on Casual for a friendlier draft, then put back any ticket keys, row limits or endpoint paths it may have reworded.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F8ruchpl2tjfywcm5llm1.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F8ruchpl2tjfywcm5llm1.png" alt="Rephrase AI Casual profile rewording a Jira description while keeping the 5,000 row detail" width="799" height="358"&gt;&lt;/a&gt;&lt;br&gt;
&lt;em&gt;Rewriting a Jira ticket line on the Casual profile in Rephrase AI with the 5,000 row detail kept.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>productivity</category>
      <category>agile</category>
      <category>writing</category>
      <category>devops</category>
    </item>
    <item>
      <title>API documentation examples and how to rewrite unclear endpoint docs</title>
      <dc:creator>Gabe Garcia</dc:creator>
      <pubDate>Thu, 29 Oct 2026 18:08:03 +0000</pubDate>
      <link>https://dev.to/gabegarcia_rephrase/api-documentation-examples-and-how-to-rewrite-unclear-endpoint-docs-4glj</link>
      <guid>https://dev.to/gabegarcia_rephrase/api-documentation-examples-and-how-to-rewrite-unclear-endpoint-docs-4glj</guid>
      <description>&lt;p&gt;Most API docs are written by the people who built the API. That's why they're accurate and still hard to use. The author already knows what a "resource" is, which field is required and why the call returns 409. The reader doesn't.&lt;/p&gt;

&lt;p&gt;This post walks through API documentation examples for the parts first time users read most. Endpoint summaries, parameter tables, request and response samples, error docs and auth steps. Each section shows a terse version and a clearer rewrite.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a reader needs from an endpoint page
&lt;/h2&gt;

&lt;p&gt;A developer landing on an endpoint page wants to answer five questions fast.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;What does this call do?&lt;/li&gt;
&lt;li&gt;What do I have to send?&lt;/li&gt;
&lt;li&gt;What will I get back?&lt;/li&gt;
&lt;li&gt;What can go wrong?&lt;/li&gt;
&lt;li&gt;Can I copy something that works?&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If your page answers those in that order, you're ahead of most docs.&lt;/p&gt;

&lt;h2&gt;
  
  
  Endpoint summaries
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Terse.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;POST /v1/invoices. Creates invoice object.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Clearer.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;POST /v1/invoices creates a draft invoice for a customer. The invoice isn't sent until you call the send endpoint, so you can add line items first.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The rewrite says what happens and what doesn't. That second sentence prevents a support ticket.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Terse.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;DELETE /v1/webhooks/{id}. Deletes webhook.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Clearer.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;DELETE /v1/webhooks/{id} stops sending events to that URL right away. Events already queued are dropped. This can't be undone, but you can create a new webhook with the same URL.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Parameter tables
&lt;/h2&gt;

&lt;p&gt;A parameter table should say the type, whether it's required, the default and one plain sentence on what it changes.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Terse.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Name&lt;/th&gt;
&lt;th&gt;Type&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;due&lt;/td&gt;
&lt;td&gt;int&lt;/td&gt;
&lt;td&gt;Due date&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;cur&lt;/td&gt;
&lt;td&gt;string&lt;/td&gt;
&lt;td&gt;Currency&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Clearer.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Name&lt;/th&gt;
&lt;th&gt;Type&lt;/th&gt;
&lt;th&gt;Required&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;due_date&lt;/td&gt;
&lt;td&gt;integer&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Unix timestamp for when payment is due. Defaults to 30 days after creation.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;currency&lt;/td&gt;
&lt;td&gt;string&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Three letter ISO code in lowercase, such as &lt;code&gt;usd&lt;/code&gt; or &lt;code&gt;eur&lt;/code&gt;. Must match the customer's default currency.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Renaming the fields in the API is a bigger job, but you can always fix the description column today.&lt;/p&gt;

&lt;h2&gt;
  
  
  Request and response samples
&lt;/h2&gt;

&lt;p&gt;Give a full example someone can paste into a terminal. Include headers, a realistic body and the response they'll see.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl https://api.example.com/v1/invoices &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-H&lt;/span&gt; &lt;span class="s2"&gt;"Authorization: Bearer sk_test_123"&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-H&lt;/span&gt; &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-d&lt;/span&gt; &lt;span class="s1"&gt;'{
    "customer_id": "cus_8842",
    "currency": "usd",
    "due_date": 1767225600
  }'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"inv_2051"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"draft"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"customer_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"cus_8842"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"currency"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"usd"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"amount_due"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"due_date"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;1767225600&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then add one line explaining anything surprising. Here that's that &lt;code&gt;amount_due&lt;/code&gt; stays at zero until you add line items. People will assume it's a bug otherwise.&lt;/p&gt;

&lt;h2&gt;
  
  
  Error documentation
&lt;/h2&gt;

&lt;p&gt;Error docs are where terse writing hurts the most, because the reader is already stuck.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Terse.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;409 Conflict. Resource state conflict.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Clearer.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;409 Conflict means the invoice has already been sent, so it can't be edited. To change it, void the invoice and create a new one. The response body includes &lt;code&gt;current_status&lt;/code&gt; so you can check before retrying.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;A good pattern for every error is three parts. What happened, why it usually happens and what to do next.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"error"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"code"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"invoice_not_editable"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"message"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Invoice inv_2051 was sent and can no longer be edited."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"hint"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Void it with POST /v1/invoices/inv_2051/void and create a new draft."&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you control the API, put that hint in the response itself. The best error docs are the ones developers never have to open.&lt;/p&gt;

&lt;h2&gt;
  
  
  Authentication steps
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Terse.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Auth via bearer token. See dashboard.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Clearer.&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Every request needs an API key in the Authorization header. Create a key in the dashboard under Settings, then API keys. Test keys start with &lt;code&gt;sk_test_&lt;/code&gt; and never move real money. Live keys start with &lt;code&gt;sk_live_&lt;/code&gt; and should only live in server side code.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Spell out where the button is. "See dashboard" assumes the reader has already found it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick checks before you publish
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Read it as a newcomer.&lt;/strong&gt; Load the docs in an incognito tab and attempt the first call with nothing else to lean on.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Define every noun once.&lt;/strong&gt; If "workspace" and "account" mean different things, say so near the top.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use the same names everywhere.&lt;/strong&gt; If the field is &lt;code&gt;customer_id&lt;/code&gt;, don't call it "client ID" in the prose.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Show the unhappy path.&lt;/strong&gt; One example of a failed request teaches as much as three successful ones.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Date your changes.&lt;/strong&gt; A short note on when behavior changed saves people from debugging old blog posts.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Rewriting long explanations
&lt;/h2&gt;

&lt;p&gt;Endpoint summaries are short, but concept pages, like how pagination or rate limits work, often turn into walls of text. When you're rewriting those, it helps to see how others restructure dense prose. These &lt;a href="https://www.rephraseai.com/blog/paragraph-rephraser-examples" rel="noopener noreferrer"&gt;paragraph rephraser examples&lt;/a&gt; show long paragraphs split into clearer sentences while the meaning holds.&lt;/p&gt;

&lt;p&gt;For a concept page you've stared at too long, run one paragraph through &lt;a href="https://rephraseai.com" rel="noopener noreferrer"&gt;Rephrase AI&lt;/a&gt; to get fresh wording to compare, and then check that every field name, status code and limit in the new version still matches your spec.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fimk75wpdwggphz883jq0.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fimk75wpdwggphz883jq0.png" alt="Rephrase AI paragraph rephraser on Clearer turning a terse endpoint line into a clear description" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Expanding a terse endpoint line into a clear description with Rephrase AI's paragraph rephraser on Clearer.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Docs aren't done when they're accurate. They're done when someone new can make their first call without asking you anything.&lt;/p&gt;

</description>
      <category>api</category>
      <category>documentation</category>
      <category>writing</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Acceptance criteria examples developers can test</title>
      <dc:creator>Gabe Garcia</dc:creator>
      <pubDate>Thu, 29 Oct 2026 16:35:23 +0000</pubDate>
      <link>https://dev.to/gabegarcia_rephrase/acceptance-criteria-examples-developers-can-test-4nij</link>
      <guid>https://dev.to/gabegarcia_rephrase/acceptance-criteria-examples-developers-can-test-4nij</guid>
      <description>&lt;p&gt;Acceptance criteria are the conditions a change must meet before anyone calls it done. When they're good, QA, product and engineering all agree on what "done" means before the first commit. When they're bad, that argument happens in code review.&lt;/p&gt;

&lt;p&gt;This post is a set of acceptance criteria examples in the two formats most teams use, a few ambiguous tickets rewritten into testable ones and a sketch of how criteria turn straight into automated tests.&lt;/p&gt;

&lt;h2&gt;
  
  
  Two formats, two jobs
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Scenario style&lt;/strong&gt; uses Given, When and Then. It fits behavior with a clear trigger and outcome, like a checkout flow or a permission rule.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rule style&lt;/strong&gt; is a plain checklist. It fits constraints that don't have a natural sequence, like field limits, layout rules or performance budgets.&lt;/p&gt;

&lt;h2&gt;
  
  
  Scenario style examples
&lt;/h2&gt;

&lt;p&gt;Here's a password reset feature written in Gherkin.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight gherkin"&gt;&lt;code&gt;&lt;span class="kd"&gt;Feature&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; Password reset

  &lt;span class="kn"&gt;Scenario&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; Reset link sent for a known email
    &lt;span class="nf"&gt;Given &lt;/span&gt;an account exists for &lt;span class="s"&gt;"ana@example.com"&lt;/span&gt;
    &lt;span class="nf"&gt;When &lt;/span&gt;I request a password reset for &lt;span class="s"&gt;"ana@example.com"&lt;/span&gt;
    &lt;span class="nf"&gt;Then &lt;/span&gt;a reset email is sent to &lt;span class="s"&gt;"ana@example.com"&lt;/span&gt;
    &lt;span class="nf"&gt;And &lt;/span&gt;the link in the email expires after 30 minutes

  &lt;span class="kn"&gt;Scenario&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; Same response for an unknown email
    &lt;span class="nf"&gt;Given &lt;/span&gt;no account exists for &lt;span class="s"&gt;"ghost@example.com"&lt;/span&gt;
    &lt;span class="nf"&gt;When &lt;/span&gt;I request a password reset for &lt;span class="s"&gt;"ghost@example.com"&lt;/span&gt;
    &lt;span class="nf"&gt;Then &lt;/span&gt;I see the message &lt;span class="s"&gt;"If that address has an account, we've sent a link"&lt;/span&gt;
    &lt;span class="nf"&gt;And &lt;/span&gt;no email is sent

  &lt;span class="kn"&gt;Scenario&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; Expired link
    &lt;span class="nf"&gt;Given &lt;/span&gt;I have a reset link that is 31 minutes old
    &lt;span class="nf"&gt;When &lt;/span&gt;I open the link
    &lt;span class="nf"&gt;Then &lt;/span&gt;I see &lt;span class="s"&gt;"This link has expired"&lt;/span&gt;
    &lt;span class="nf"&gt;And &lt;/span&gt;I am offered a button to request a new one
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few things make these testable. Every Then is observable. Numbers are explicit. The second scenario pins down a security rule, so nobody has to guess whether to reveal which emails exist.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule style examples
&lt;/h2&gt;

&lt;p&gt;A profile form, written as a checklist.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="p"&gt;-&lt;/span&gt; [ ] Display name is required, 2 to 40 characters
&lt;span class="p"&gt;-&lt;/span&gt; [ ] Leading and trailing spaces are trimmed before saving
&lt;span class="p"&gt;-&lt;/span&gt; [ ] Bio is optional, max 280 characters, with a live counter
&lt;span class="p"&gt;-&lt;/span&gt; [ ] Avatar accepts PNG or JPEG up to 5 MB
&lt;span class="p"&gt;-&lt;/span&gt; [ ] Saving shows a "Profile updated" toast and keeps the page scroll position
&lt;span class="p"&gt;-&lt;/span&gt; [ ] All fields are reachable and operable by keyboard alone
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each line can be checked as true or false.&lt;/p&gt;

&lt;h2&gt;
  
  
  Ambiguous tickets, rewritten
&lt;/h2&gt;

&lt;p&gt;These are the kinds of lines that cause rework. Each rewrite says the same thing in a way a test can check.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Before: Search should be fast.
After:  Search results render within 300 ms at p95 for a catalog of 50k items.

Before: Handle errors gracefully.
After:  If the payment API returns 5xx, show "Payment didn't go through, you
        weren't charged" and keep the cart intact.

Before: The table should work on mobile.
After:  At widths under 640px, the table collapses into stacked cards with
        the order number as each card's heading.

Before: Admins can manage members.
After:  Admins can invite, remove and change the role of members.
        Removing the last admin is blocked with an inline message.

Before: Support bulk upload.
After:  CSV upload accepts up to 10,000 rows. Rows with errors are skipped
        and listed in a downloadable report with row number and reason.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The pattern is always the same. Replace adjectives with numbers, replace verbs like "manage" with a list of actions and name what the person sees when things fail.&lt;/p&gt;

&lt;h2&gt;
  
  
  Turning criteria into tests
&lt;/h2&gt;

&lt;p&gt;Good criteria map almost line for line onto tests. Here's the expired link scenario as a Playwright sketch.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;test&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;expect&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@playwright/test&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;createResetToken&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;./helpers/auth&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;expired reset link offers a new one&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;page&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;token&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;createResetToken&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ana@example.com&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;ageMinutes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;31&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;goto&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`/reset?token=&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;token&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getByText&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;This link has expired&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)).&lt;/span&gt;&lt;span class="nf"&gt;toBeVisible&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nx"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getByRole&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;button&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Send a new link&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;
  &lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toBeVisible&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And one profile rule as a unit test.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;describe&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;it&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;expect&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;vitest&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;validateProfile&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;../src/profile&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;describe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;display name&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;it&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;trims spaces before checking length&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;validateProfile&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;displayName&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;  Al  &lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nx"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;validateProfile&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;displayName&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt; A &lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nx"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="nf"&gt;it&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;rejects names over 40 characters&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;long&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;x&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;repeat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;41&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;validateProfile&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;displayName&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;long&lt;/span&gt; &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nx"&gt;errors&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toContain&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;displayName.max&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you can't sketch a test for a criterion in a minute or two, the criterion probably isn't specific enough yet.&lt;/p&gt;

&lt;h2&gt;
  
  
  Don't forget the non-functional lines
&lt;/h2&gt;

&lt;p&gt;Teams often write criteria for the happy path and skip everything else. Add a line for each of these when it matters.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Accessibility.&lt;/strong&gt; Focus order, labels and color contrast.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Performance.&lt;/strong&gt; A budget with a percentile, like p95 under 300 ms.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Security.&lt;/strong&gt; Who can see or do this, and what happens if they can't.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Analytics.&lt;/strong&gt; The event names and properties that should fire.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Empty and error states.&lt;/strong&gt; What shows when there's no data or the call fails.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Common mistakes
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Writing the implementation.&lt;/strong&gt; "Use a Redis cache" is a design choice. State the outcome and let engineers choose.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Untestable words.&lt;/strong&gt; Fast, intuitive, user-friendly and robust can't fail a test.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Criteria written after the code.&lt;/strong&gt; They turn into a description of what was built, not what was needed.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Too many scenarios.&lt;/strong&gt; If a ticket has fifteen, it's probably two or three tickets.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Before the ticket moves to ready
&lt;/h2&gt;

&lt;p&gt;Read each criterion and ask whether a new teammate could write a failing test for it today. If not, rewrite it.&lt;/p&gt;

&lt;p&gt;Long criteria often hide a simple rule. A short guide on the habit you need here, &lt;a href="https://www.rephraseai.com/blog/how-to-simplify-text-without-changing-meaning" rel="noopener noreferrer"&gt;simplify text without changing meaning&lt;/a&gt;, shows how to pull it out and keep every condition.&lt;/p&gt;

&lt;p&gt;When a whole block of criteria reads dense, &lt;a href="https://rephraseai.com" rel="noopener noreferrer"&gt;Rephrase AI&lt;/a&gt; can reword it in plainer sentences, and then a side by side read confirms every number and edge case survived.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F72zuk93030d64g4jlma4.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F72zuk93030d64g4jlma4.png" alt="Rephrase AI rewording tool on Clearer restating CSV upload acceptance criteria while keeping the 10,000 row limit" width="800" height="648"&gt;&lt;/a&gt;&lt;br&gt;
&lt;em&gt;Rewording CSV upload acceptance criteria in Rephrase AI on Clearer with the 10,000 row limit kept.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Clear criteria won't write the code for you. They do make the review a lot shorter.&lt;/p&gt;

</description>
      <category>agile</category>
      <category>testing</category>
      <category>productivity</category>
      <category>writing</category>
    </item>
    <item>
      <title>Changelog examples with annotated entries and noisy ones rewritten</title>
      <dc:creator>Gabe Garcia</dc:creator>
      <pubDate>Thu, 29 Oct 2026 16:15:14 +0000</pubDate>
      <link>https://dev.to/gabegarcia_rephrase/changelog-examples-with-annotated-entries-and-noisy-ones-rewritten-12od</link>
      <guid>https://dev.to/gabegarcia_rephrase/changelog-examples-with-annotated-entries-and-noisy-ones-rewritten-12od</guid>
      <description>&lt;p&gt;A changelog is the file a developer opens when they're about to bump a dependency and want to know what will break. It isn't marketing and it isn't a dump of your git log. It's a curated, dated history of notable changes to the project, kept in the repo next to the code.&lt;/p&gt;

&lt;p&gt;Below are changelog examples in the Keep a Changelog style, with notes on why each part is there, followed by noisy entries rewritten into ones a maintainer can scan.&lt;/p&gt;

&lt;h2&gt;
  
  
  A minimal file that works
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gh"&gt;# Changelog&lt;/span&gt;

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

&lt;span class="gu"&gt;## [Unreleased]&lt;/span&gt;

&lt;span class="gu"&gt;### Added&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="sb"&gt;`--dry-run`&lt;/span&gt; flag for &lt;span class="sb"&gt;`sync`&lt;/span&gt; that prints planned writes without applying them.

&lt;span class="gu"&gt;## [2.4.0] - 2026-10-12&lt;/span&gt;

&lt;span class="gu"&gt;### Added&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="sb"&gt;`retry.maxDelay`&lt;/span&gt; option to cap exponential backoff.

&lt;span class="gu"&gt;### Changed&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="sb"&gt;`connect()`&lt;/span&gt; now times out after 30s by default, up from 10s.

&lt;span class="gu"&gt;### Deprecated&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="sb"&gt;`client.legacyAuth()`&lt;/span&gt;. Use &lt;span class="sb"&gt;`client.auth({ mode: "token" })`&lt;/span&gt; instead.
  Scheduled for removal in 3.0.0.

&lt;span class="gu"&gt;### Fixed&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Memory leak when a stream was closed before the first chunk. #812

&lt;span class="gu"&gt;## [2.3.1] - 2026-09-03&lt;/span&gt;

&lt;span class="gu"&gt;### Security&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Reject redirects to non-HTTPS hosts when &lt;span class="sb"&gt;`strictTls`&lt;/span&gt; is set. CVE-2026-0000

&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="ss"&gt;Unreleased&lt;/span&gt;&lt;span class="p"&gt;]:&lt;/span&gt; &lt;span class="sx"&gt;../../compare/v2.4.0...HEAD&lt;/span&gt;
&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="ss"&gt;2.4.0&lt;/span&gt;&lt;span class="p"&gt;]:&lt;/span&gt; &lt;span class="sx"&gt;../../compare/v2.3.1...v2.4.0&lt;/span&gt;
&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="ss"&gt;2.3.1&lt;/span&gt;&lt;span class="p"&gt;]:&lt;/span&gt; &lt;span class="sx"&gt;../../compare/v2.3.0...v2.3.1&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fu8ss9b3qms00m9ztz4dj.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fu8ss9b3qms00m9ztz4dj.png" alt="Keep a Changelog 1.1.0 home page showing its example CHANGELOG.md with Unreleased and Added sections" width="800" height="500"&gt;&lt;/a&gt;&lt;br&gt;
&lt;em&gt;Screenshot from &lt;a href="https://keepachangelog.com/en/1.1.0/" rel="noopener noreferrer"&gt;Keep a Changelog&lt;/a&gt;, MIT License&lt;/em&gt;&lt;/p&gt;
&lt;h2&gt;
  
  
  Annotations, part by part
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;The header lines.&lt;/strong&gt; Two sentences tell a reader what the file promises. Saying you follow semantic versioning sets expectations. A minor bump shouldn't break their build.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Unreleased at the top.&lt;/strong&gt; Changes land here as they merge. On release day you rename the heading to the version and date. Nobody has to dig through commits the night before.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Newest version first.&lt;/strong&gt; People open the file to see what changed lately, so the latest release sits on top.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;ISO dates.&lt;/strong&gt; &lt;code&gt;2026-10-12&lt;/code&gt; sorts cleanly and reads the same in every country.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The six change types.&lt;/strong&gt; Added, Changed, Deprecated, Removed, Fixed and Security. Grouping by type lets someone jump straight to the part that affects them. A reader who only cares about breaking changes reads Changed and Removed and moves on.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Code formatting for names.&lt;/strong&gt; Flags, options and functions are in backticks, so they're searchable and copyable.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Old and new values.&lt;/strong&gt; "30s by default, up from 10s" saves a trip to the diff.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A migration path on deprecations.&lt;/strong&gt; Every deprecation names the replacement and the version where the old thing goes away.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Compare links at the bottom.&lt;/strong&gt; Each version heading links to a diff between tags. The changelog stays short, and the full detail is one click away.&lt;/p&gt;
&lt;h2&gt;
  
  
  Noisy entries, rewritten
&lt;/h2&gt;

&lt;p&gt;Most bad changelogs come from pasting commit subjects straight in. Here's what that tends to look like.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gu"&gt;## 2.4.0&lt;/span&gt;
&lt;span class="p"&gt;
-&lt;/span&gt; Merge pull request #799 from dev/feature-branch
&lt;span class="p"&gt;-&lt;/span&gt; fix
&lt;span class="p"&gt;-&lt;/span&gt; Updated deps
&lt;span class="p"&gt;-&lt;/span&gt; refactor client
&lt;span class="p"&gt;-&lt;/span&gt; WIP retry stuff
&lt;span class="p"&gt;-&lt;/span&gt; Fixed the thing Sam reported
&lt;span class="p"&gt;-&lt;/span&gt; bump version
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Every line here is true and almost none of it helps. Merge commits, version bumps and refactors with no visible effect don't belong. "The thing Sam reported" means nothing outside your team chat. Here's the same release, cleaned up.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gu"&gt;## [2.4.0] - 2026-10-12&lt;/span&gt;

&lt;span class="gu"&gt;### Added&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="sb"&gt;`retry.maxDelay`&lt;/span&gt; option to cap exponential backoff. #799

&lt;span class="gu"&gt;### Changed&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Bump &lt;span class="sb"&gt;`undici`&lt;/span&gt; to 6.x. Node 18 is now the minimum version.

&lt;span class="gu"&gt;### Fixed&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="sb"&gt;`parse()`&lt;/span&gt; no longer throws on empty response bodies. #805
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Seven lines became three, and each one tells a reader whether they need to act. The dependency bump stayed because it changes the supported Node range. That's the only reason a reader would care about it.&lt;/p&gt;

&lt;h2&gt;
  
  
  One more before and after
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="p"&gt;-&lt;/span&gt; Changed how config loading works to be more flexible and also fixed
  some edge cases around env vars that could cause issues in some setups
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gu"&gt;### Changed&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Config files are now merged in order. Later files override earlier ones.

&lt;span class="gu"&gt;### Fixed&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Empty env vars no longer override values set in a config file. #788
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The original mixed a behavior change and a bug fix in one long sentence. Splitting them puts each under the right heading. It also makes the breaking part easy to spot.&lt;/p&gt;

&lt;h2&gt;
  
  
  Habits that keep the file useful
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Update &lt;code&gt;CHANGELOG.md&lt;/code&gt; in the same pull request as the change. A CI check that fails when &lt;code&gt;src/&lt;/code&gt; changes without a changelog edit works well on busy repos.&lt;/li&gt;
&lt;li&gt;Write each line for someone who hasn't read the code.&lt;/li&gt;
&lt;li&gt;Mark breaking changes clearly, at the start of the line, with &lt;strong&gt;BREAKING&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Link the issue or PR number at the end, not in place of a description.&lt;/li&gt;
&lt;li&gt;If you generate the file from conventional commits, still read it before you tag. Generated entries often need a human edit.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If your entries run long, a short post on &lt;a href="https://www.rephraseai.com/blog/how-to-make-writing-shorter-without-changing-meaning" rel="noopener noreferrer"&gt;shorter writing that keeps the meaning&lt;/a&gt; covers ways to trim a line without losing the detail. When a whole release section feels wordy, &lt;a href="https://rephraseai.com" rel="noopener noreferrer"&gt;Rephrase AI&lt;/a&gt; can reword it with its Professional profile, and a quick diff against your draft shows whether any version number or flag name went missing. A tight changelog makes every upgrade an easier call.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0pxlh78x1jx9vv1f696b.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0pxlh78x1jx9vv1f696b.png" alt="Rephrase AI rewriter on Professional rewording a noisy changelog entry about config loading and env vars" width="800" height="648"&gt;&lt;/a&gt;&lt;br&gt;
&lt;em&gt;Rewording a noisy changelog entry about config loading with Rephrase AI on Professional.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>changelog</category>
      <category>documentation</category>
      <category>writing</category>
      <category>opensource</category>
    </item>
    <item>
      <title>Git commit message best practices with before and after rewrites</title>
      <dc:creator>Gabe Garcia</dc:creator>
      <pubDate>Tue, 27 Oct 2026 16:40:10 +0000</pubDate>
      <link>https://dev.to/gabegarcia_rephrase/git-commit-message-best-practices-with-before-and-after-rewrites-1po</link>
      <guid>https://dev.to/gabegarcia_rephrase/git-commit-message-best-practices-with-before-and-after-rewrites-1po</guid>
      <description>&lt;h1&gt;
  
  
  How to write commit messages your future self can search, plus conventional commits
&lt;/h1&gt;

&lt;p&gt;Run &lt;code&gt;git log --oneline&lt;/code&gt; on almost any project and you'll find a stretch like this.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;a1f3c2e wip
9be07d1 fix
3c44a9f more fixes
e02b8d1 asdf
7d1f6aa final changes for real
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Every one of those commits was obvious to the person who wrote it, on the day they wrote it. A year later, during a &lt;code&gt;git bisect&lt;/code&gt; at 11 PM, none of them mean anything.&lt;/p&gt;

&lt;p&gt;These are the git commit message best practices that fix that, each shown with a before and after rewrite, plus how conventional commits fit on top.&lt;/p&gt;

&lt;h2&gt;
  
  
  The seven habits that matter
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Separate the subject from the body with a blank line.&lt;/li&gt;
&lt;li&gt;Keep the subject around 50 characters, and wrap the body near 72.&lt;/li&gt;
&lt;li&gt;Capitalize the subject and skip the trailing period.&lt;/li&gt;
&lt;li&gt;Write the subject as a command, as in "Add", "Remove" or "Rename".&lt;/li&gt;
&lt;li&gt;Say what changed and why. The diff already shows how.&lt;/li&gt;
&lt;li&gt;Make one logical change per commit.&lt;/li&gt;
&lt;li&gt;Reference the issue or ticket in the body or footer, not as the whole message.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;A handy test for the subject is to finish the sentence "If applied, this commit will..." with it. "If applied, this commit will add rate limiting to the login endpoint" reads well. "If applied, this commit will fixed stuff" doesn't.&lt;/p&gt;

&lt;h2&gt;
  
  
  Before and after rewrites
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Vague subject&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;fix
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Prevent duplicate invoices when checkout is retried
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first tells you nothing. The second says what broke, from the outside, so anyone searching the log for "invoice" finds it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Subject that's really a diary entry&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Finally got the date picker working after hours of pain
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Fix date picker ignoring the locale's first day of week
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Feelings belong in the team chat. The log is for facts.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Everything in one commit&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;update settings page, fix typo in readme, bump eslint
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Split it into three commits.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Add timezone selector to settings page
Fix typo in README install steps
Bump eslint from 8.56 to 8.57
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now each one can be reverted on its own, and blame points to the right change.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Missing the why&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Change cache TTL to 300
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Lower product cache TTL to 5 minutes

Prices stayed stale for up to an hour after edits in the admin
panel, which caused support tickets during sales. Five minutes
keeps database load low while letting price changes show up
soon after they're saved.

Refs #812
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The subject tells you what. The body tells the next developer not to raise it back to an hour without thinking.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where conventional commits fit
&lt;/h2&gt;

&lt;p&gt;Conventional commits is a spec for a structured subject line. It adds a type and an optional scope in front of the description.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;&amp;lt;type&amp;gt;(&amp;lt;scope&amp;gt;): &amp;lt;description&amp;gt;

[optional body]

[optional footer(s)]
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Common types are &lt;code&gt;feat&lt;/code&gt;, &lt;code&gt;fix&lt;/code&gt;, &lt;code&gt;docs&lt;/code&gt;, &lt;code&gt;refactor&lt;/code&gt;, &lt;code&gt;test&lt;/code&gt;, &lt;code&gt;perf&lt;/code&gt;, &lt;code&gt;build&lt;/code&gt;, &lt;code&gt;ci&lt;/code&gt; and &lt;code&gt;chore&lt;/code&gt;. A &lt;code&gt;!&lt;/code&gt; after the type, or a &lt;code&gt;BREAKING CHANGE&lt;/code&gt; footer, marks a breaking change.&lt;/p&gt;

&lt;p&gt;Here's the cache example in that style.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;fix(cache): lower product cache TTL to 5 minutes

Prices stayed stale for up to an hour after admin edits.

Refs #812
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And a breaking one.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;feat(api)!: require an API key for all v2 endpoints

BREAKING CHANGE: anonymous requests to /v2 now return 401.
Clients must send the X-Api-Key header.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Most teams using the convention write lowercase descriptions, which clashes with habit 3. Pick one rule per repo and stick to it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why teams adopt it
&lt;/h2&gt;

&lt;p&gt;The structure is machine readable. Tools can generate changelogs from &lt;code&gt;feat&lt;/code&gt; and &lt;code&gt;fix&lt;/code&gt; commits and work out the next semantic version. A &lt;code&gt;fix&lt;/code&gt; maps to a patch, a &lt;code&gt;feat&lt;/code&gt; to a minor and a breaking change to a major.&lt;/p&gt;

&lt;p&gt;It also nudges people to think in single changes. If you can't pick one type for a commit, it's probably two commits.&lt;/p&gt;

&lt;h2&gt;
  
  
  When it's overkill
&lt;/h2&gt;

&lt;p&gt;On a solo side project with no releases, the type prefix can be noise. The seven habits above matter more than the prefix. A clear plain subject beats a typed prefix followed by "stuff" every time.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make it easy to do right
&lt;/h2&gt;

&lt;p&gt;Set a real editor for commits so you're not cramming everything into &lt;code&gt;-m&lt;/code&gt;. Add a commit template with &lt;code&gt;git config commit.template ~/.gitmessage&lt;/code&gt; that reminds you of the subject and body shape. If your team uses conventional commits, run commitlint in a hook or a CI step so the format gets checked for you.&lt;/p&gt;

&lt;p&gt;Finally, read your subject line cold, the way a stranger to the code would. If it only makes sense with context in your head, rewrite it. &lt;a href="https://rephraseai.com" rel="noopener noreferrer"&gt;Rephrase AI&lt;/a&gt; keeps what a sentence means while changing the words, and you can line the result up against your first draft before you commit. Its blog also has a short post on ways to &lt;a href="https://www.rephraseai.com/blog/how-to-rephrase-text-for-clarity" rel="noopener noreferrer"&gt;rephrase text for clarity&lt;/a&gt;, and the same ideas work on a commit body. Your teammates, and you in a year, will be able to search the history and find what they need.&lt;/p&gt;

</description>
      <category>git</category>
      <category>beginners</category>
      <category>productivity</category>
      <category>bestpractices</category>
    </item>
    <item>
      <title>Best free paraphrasing tools with no sign-up in 2027</title>
      <dc:creator>Gabe Garcia</dc:creator>
      <pubDate>Mon, 26 Oct 2026 22:41:14 +0000</pubDate>
      <link>https://dev.to/gabegarcia_rephrase/best-free-paraphrasing-tools-with-no-sign-up-in-2027-1kbc</link>
      <guid>https://dev.to/gabegarcia_rephrase/best-free-paraphrasing-tools-with-no-sign-up-in-2027-1kbc</guid>
      <description>&lt;h1&gt;
  
  
  Rewording commit messages, PR descriptions and docs with free tools that skip the account
&lt;/h1&gt;

&lt;p&gt;Most developers write more prose than they admit. Commit messages, pull request descriptions, error strings, README sections, API reference pages. None of it compiles, so it gets written last, usually in a rush. Then a teammate reads it six months later and has no idea what changed or why.&lt;/p&gt;

&lt;p&gt;A free paraphraser won't fix bad thinking, but it can help when you know what you mean and the sentence won't cooperate. This post covers five tools you can open in a browser tab and use without creating an account, based on what each tool's own site said when I checked on October 26, 2026. Each one has a limit somewhere, and I'll point it out.&lt;/p&gt;

&lt;p&gt;One rule before any of this. Don't paste secrets, tokens, internal hostnames or customer data into a public web tool. Strip those out first or leave the text alone.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where rewording actually helps in a dev workflow
&lt;/h2&gt;

&lt;p&gt;Here are the spots where a second pass on the wording pays off.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Commit messages.&lt;/strong&gt; The subject line should say what the change does, not how you felt while making it. A tool can turn a vague note into a short imperative line.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;PR descriptions.&lt;/strong&gt; Reviewers want the reason, the change and how to test it. Rambling descriptions slow the review down.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Error messages.&lt;/strong&gt; People read these when they're already annoyed. A good one says what went wrong and what to try next.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;README text.&lt;/strong&gt; The opening paragraph decides whether someone keeps reading or closes the tab.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;API docs.&lt;/strong&gt; Parameter descriptions tend to drift into jargon. Plain wording means fewer support questions.&lt;/p&gt;

&lt;p&gt;Here's a commit message before and after a rewrite. I wrote both versions by hand to show the target, so this isn't output from any tool below.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Before&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;fixed the bug where uploads sometimes failed, it was because the retry
logic wasn't waiting long enough so I changed it, also cleaned up some stuff
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;After&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Increase upload retry backoff to stop intermittent failures

The retry loop used a fixed 200ms delay, which was too short when the
storage service was under load. Switch to exponential backoff capped
at 5s. Also remove two unused helper functions in upload.js.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And an error string, same deal, written by hand.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Before&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Error, operation could not be completed due to invalid input parameters
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;After&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Couldn't save the webhook because the URL field is empty. Add a URL and try again.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The pattern in both is the same. Say what happened, say why and say what to do next. A paraphraser is useful for getting from the first draft to something close to the second, and then you edit the rest.&lt;/p&gt;

&lt;h2&gt;
  
  
  The tools
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Rephrase AI
&lt;/h3&gt;

&lt;p&gt;The paraphrasing tool page on &lt;a href="https://rephraseai.com" rel="noopener noreferrer"&gt;Rephrase AI&lt;/a&gt; works signed out. You paste up to 1,200 characters into the preview box, pick Clearer, Professional or Shorter, and get a reworded version back. I ran a test sentence through it while signed out and it returned a rewrite with no login prompt. Clearer and Shorter are the useful styles for commit subjects and error strings.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fuaqak48h1knwi12faknf.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fuaqak48h1knwi12faknf.png" alt="Rephrase AI paraphrasing tool on Clearer used signed out, rewording an academic sentence" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Rewording an academic sentence in Rephrase AI's paraphrasing tool on Clearer, without signing in.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The full workspace needs sign-in. That's where the four profiles live. You start from Casual, Academic, Professional or Creative, then set creativity, brevity, formality and complexity to taste. There's also a SuperRephrase Mode for a deeper pass, and a side by side view puts the old text beside the rewritten one, which helps when you're checking that a technical term didn't change. A free account gets 3 rephrases a month, and each one can hold 3,000 characters. Pro removes the monthly cap and raises the per rephrase limit to 10,000 characters.&lt;/p&gt;

&lt;h3&gt;
  
  
  Scribbr
&lt;/h3&gt;

&lt;p&gt;Scribbr's paraphraser is free, needs no signup and shows no ads. It's powered by QuillBot and has Standard and Fluency modes. Input is capped at 125 words, so it suits a single PR paragraph or a README intro better than a whole doc page. You can click a word to get synonyms, which is handy when a parameter description keeps reusing the same verb.&lt;/p&gt;

&lt;h3&gt;
  
  
  Trinka
&lt;/h3&gt;

&lt;p&gt;Trinka's paraphraser says no sign-up is needed and takes up to 500 words per run. A slider sets the degree of change from low to high, and you can review what moved. Trinka's wider product is aimed at academic and technical writing, so the rewrites stay careful. Keep the slider low for API docs, where you want the meaning locked and only the phrasing smoothed.&lt;/p&gt;

&lt;h3&gt;
  
  
  Prepostseo
&lt;/h3&gt;

&lt;p&gt;Prepostseo offers a free version with no registration. It has ten modes, including Formal, Simplifier, Academic and Creative, and you can upload DOC, DOCX, TXT or PDF files. After a rewrite you can click a single sentence and ask for alternatives just for that line. That's useful for docs, where one sentence is confusing and the rest is fine.&lt;/p&gt;

&lt;h3&gt;
  
  
  Spinbot
&lt;/h3&gt;

&lt;p&gt;Spinbot's free version needs no sign-up and accepts up to 10,000 characters. It's a one click rewriter with almost no settings. That large limit means you can drop in a long changelog draft, but treat what comes back as raw material and edit it by hand.&lt;/p&gt;

&lt;h2&gt;
  
  
  How to keep technical meaning intact
&lt;/h2&gt;

&lt;p&gt;Paraphrasers don't know your codebase. They'll happily swap words that matter.&lt;/p&gt;

&lt;p&gt;Freeze identifiers first. Put function names, flags, file paths and env vars in backticks, or replace them with placeholders, and put them back after.&lt;/p&gt;

&lt;p&gt;Watch for verbs that change behavior. "Retries" and "repeats" aren't the same thing to a reader debugging a queue. Neither are "deprecated" and "removed".&lt;/p&gt;

&lt;p&gt;Check numbers and units. A 30 second timeout shouldn't come back as "a short timeout".&lt;/p&gt;

&lt;p&gt;Keep commit subjects under about 50 characters and in the imperative. Most tools won't enforce that, so trim by hand.&lt;/p&gt;

&lt;p&gt;Read the diff, not just the output. If the tool changed what the sentence claims, throw that version away.&lt;/p&gt;

&lt;h2&gt;
  
  
  Picking one
&lt;/h2&gt;

&lt;p&gt;For a single commit subject or error string, the Rephrase AI preview with Clearer or Shorter is a reasonable first try. For one PR or README paragraph, Scribbr's 125 word box fits. For API docs where meaning has to stay put, Trinka on a low setting is the careful choice. For a doc page with one or two bad sentences, Prepostseo's per line alternatives save time. For a long changelog you'll rework anyway, Spinbot takes the biggest paste.&lt;/p&gt;

&lt;p&gt;None of them replace knowing what your change does. They just help you say it in fewer, clearer words, so the next person reading your history doesn't have to guess.&lt;/p&gt;

</description>
      <category>writing</category>
      <category>productivity</category>
      <category>git</category>
      <category>documentation</category>
    </item>
    <item>
      <title>How to reword README and docs text so developers actually get it</title>
      <dc:creator>Gabe Garcia</dc:creator>
      <pubDate>Mon, 26 Oct 2026 21:52:34 +0000</pubDate>
      <link>https://dev.to/gabegarcia_rephrase/how-to-reword-readme-and-docs-text-so-developers-actually-get-it-5ehn</link>
      <guid>https://dev.to/gabegarcia_rephrase/how-to-reword-readme-and-docs-text-so-developers-actually-get-it-5ehn</guid>
      <description>&lt;p&gt;Most docs aren't wrong. They're written by the person who knows the code best, at the moment they know it best. That's the problem. Every shortcut makes sense to the author and almost none of it makes sense to someone cloning the repo for the first time.&lt;/p&gt;

&lt;p&gt;You don't need to rewrite your docs from scratch. You need to reword the parts people read first and the parts they hit when something breaks. Here's how to do that for README intros, API descriptions, error messages and jargon.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rule zero. Protect the literal strings
&lt;/h2&gt;

&lt;p&gt;Before you change a single word, mark everything that has to stay exact. That means function names, flags, environment variables, file paths, config keys, version numbers and status codes. Wrap them in backticks if they aren't already.&lt;/p&gt;

&lt;p&gt;Rewording is about the prose around the code. If &lt;code&gt;MAX_RETRIES&lt;/code&gt; turns into "the maximum retry setting" in one paragraph and stays &lt;code&gt;MAX_RETRIES&lt;/code&gt; in another, readers will wonder if those are two different things. Keep identifiers frozen and let the sentences around them move.&lt;/p&gt;

&lt;h2&gt;
  
  
  README intros. Say what it is before how it works
&lt;/h2&gt;

&lt;p&gt;A README intro has one job. In two or three sentences, a stranger should know what the project does, who it's for and whether to keep reading. A lot of intros skip straight to architecture.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fveyywuajbuff2e2gtaa6.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fveyywuajbuff2e2gtaa6.png" alt="GitHub Docs page 'About the repository README file' explaining that a README should say what the project does and why it is useful" width="800" height="500"&gt;&lt;/a&gt;&lt;br&gt;
&lt;em&gt;Screenshot from &lt;a href="https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes" rel="noopener noreferrer"&gt;GitHub Docs&lt;/a&gt;, About the repository README file, CC BY 4.0&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Before&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Queuebox is a lightweight, pluggable, event driven orchestration layer
leveraging a reactive core to enable composable pipeline primitives.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;After&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Queuebox runs a series of small jobs in order and retries any that fail.
Use it when a cron script has grown too big to trust.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The rewrite trades five abstract words for a concrete action and a real situation. You can still describe the reactive core lower down. Put it after the reader knows why they'd care.&lt;/p&gt;

&lt;h2&gt;
  
  
  API descriptions. Answer the four questions
&lt;/h2&gt;

&lt;p&gt;A good description of a function or endpoint answers four things. What does it return? What does it change? What are the units? What happens by default?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Before&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;fetchUsage gets usage data for the account.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;After&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;fetchUsage returns API calls made by one account, grouped by day.
Times are in UTC. It covers the last 30 days unless you pass a start date.
It only reads data and never changes the account.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;"Gets usage data" sounds complete until someone asks which usage, over what period and in what time zone. The rewrite answers before they have to open an issue.&lt;/p&gt;

&lt;p&gt;Watch for verbs that hide side effects too. "Handles the order" could mean reads it, updates it or deletes it. Say which.&lt;/p&gt;

&lt;h2&gt;
  
  
  Error messages. What happened, why, and what to do next
&lt;/h2&gt;

&lt;p&gt;An error message is documentation that shows up at the worst moment. The reader is stuck and probably annoyed. Give them three things in plain words.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Before&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ERR_CFG_LOAD failed
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;After&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Couldn't load queuebox.yaml because line 12 isn't valid YAML.
Check the indentation on that line, then run the command again.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Keep the error code if people search for it. Just don't let the code be the whole message. And skip blame words like invalid user input or illegal operation. "Line 12 isn't valid YAML" is just as precise and a lot less hostile.&lt;/p&gt;

&lt;h2&gt;
  
  
  Jargon. Define it once or drop it
&lt;/h2&gt;

&lt;p&gt;Jargon isn't always bad. If your readers are platform engineers, "idempotent" is the right word. The trouble starts when a doc mixes audiences or uses a team's private shorthand.&lt;/p&gt;

&lt;p&gt;Ask two questions about each technical term. Would my least experienced reader know it? Is it a public term or something only my team says?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Before&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Run the bootstrap before hydrating the sidecar or the shim will 409.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;After&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Run the setup script first. If the helper container starts before setup
finishes, requests to it fail with a 409 Conflict error.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Internal nicknames like "the shim" are the worst offenders. They feel normal because you've said them a hundred times in standups. If a public term exists, use it. If you must keep a term, define it the first time it appears and use that same word every time after.&lt;/p&gt;

&lt;h2&gt;
  
  
  Acronyms and the curse of the second sentence
&lt;/h2&gt;

&lt;p&gt;Spell out an acronym the first time, unless it's something every reader knows, like API or URL. Then check the next sentence. A common pattern is defining a term in sentence one and switching to a different name for it in sentence two. Pick one name and stick with it through the whole page.&lt;/p&gt;

&lt;h2&gt;
  
  
  Read it as a new contributor
&lt;/h2&gt;

&lt;p&gt;When you're done, open the page in a private window and pretend you just found the repo. Can you tell what it does from the first screen? If a command fails, does the error point you somewhere useful? If you'd have to ask a teammate what a word means, that word needs work.&lt;/p&gt;

&lt;p&gt;Better yet, ask someone who hasn't touched the project to follow the README and narrate where they get stuck. You'll learn more in ten minutes than in an hour of rereading your own text.&lt;/p&gt;

&lt;h2&gt;
  
  
  Using a rewording tool on docs
&lt;/h2&gt;

&lt;p&gt;For a paragraph you've rewritten three times, a second version can help you see it fresh. Rephrase AI lets you paste a section, pick the Professional profile and lower complexity, then compare the result against your original. Paste one section at a time, and check that every identifier, number and code reference came back unchanged before you commit anything. The Free plan allows as many as 3,000 characters per rephrase, which is about right for one README section. More at &lt;a href="https://rephraseai.com" rel="noopener noreferrer"&gt;Rephrase AI&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fvjf6c1d16oyykqe4a3pr.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fvjf6c1d16oyykqe4a3pr.png" alt="Rephrase AI rewording tool trimming a wordy docs instruction about installing dependencies" width="800" height="500"&gt;&lt;/a&gt;&lt;br&gt;
&lt;em&gt;Rewording a README install line with Rephrase AI's rewording tool on Clearer.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>writing</category>
      <category>documentation</category>
      <category>productivity</category>
    </item>
  </channel>
</rss>
