Puan
28,728
Çözümler
0
- Konum
- Freanchey
- Mesajlar
- 3,049
- Katılım
- 2 Eki 2026
- Tepkime puanı
- 3,565
- Puan
- 28,728
- Web sitesi
- glomaxgpt.com
Table of ContentsStart by marking what must not changeThe README introAPI reference descriptionsTutorials and guidesTroubleshooting entriesChangelogs and release notesConceptual explainersWhere a humanizer fits in the docs pipelinePrompts that produce less to fixMistakes to avoidFAQTry it on one pageCommunity ArticleCommunity articles are authored by SitePoint Premium contributors. Content is screened before publication, and SitePoint reserves the right to moderate or remove articles that violate our guidelines. Views expressed are those of the authors and do not necessarily reflect those of SitePoint.Table of ContentsStart by marking what must not changeThe README introAPI reference descriptionsTutorials and guidesTroubleshooting entriesChangelogs and release notesConceptual explainersWhere a humanizer fits in the docs pipelinePrompts that produce less to fixMistakes to avoidFAQTry it on one pageHow to Humanize AI-Written Technical DocumentationDJDiv JohnPublished inAI·Best Practices·Content·October 9, 2026·Updated: October 9, 2026The AI briefing for DevelopersStay up to date with AI tools, model releases, and developer workflows that matter.Weekly. Free. One click to leave.Share this articleSitePoint PremiumStay Relevant and Grow Your Career in TechPremium ResultsPublish articles on SitePointDaily curated jobsLearning PathsDiscounts to dev toolsStart Free Trial7 Day Free Trial. Cancel Anytime.Open a README generated by a language model and the first line is almost always the same shape: “This project is a powerful and flexible library designed to simplify…” Then a Features list with eight bullets, each starting with a bolded noun. Then “Getting Started,” which tells you to install the package with a command that may or may not match the actual package name. A developer skimming it learns nothing in the first ten seconds, which is about how long they give a README before going back to the search results.
AI is useful for documentation. It’s fast at producing a first pass of an API reference from function signatures, decent at turning a Slack thread into a troubleshooting entry, and tireless about writing the boring parts nobody volunteers for. The problem is the voice. Model-written docs are padded, oddly enthusiastic, and full of hedges in the places where a reader needs certainty. Developers notice, and they start to distrust the content along with the tone.
This guide covers how to take AI-drafted docs and make them read like they came from an engineer who uses the software, with before and after examples from the parts of a docs site that suffer most.
Start by marking what must not change
Before any rewriting, by you or by a tool, identify the literal text. In technical docs, a surprising amount of content is not prose at all:
Code blocks and inline code
CLI commands and flags
Config keys, environment variable names, file paths
Version numbers, status codes, error strings
Anything a user might copy and paste
All of this must survive untouched. Paraphrasing tools treat unformatted text as ordinary words, so --dry-run written without backticks can come back as “a dry run,” and MAX_RETRIES can become “the maximum retries.” Wrap every literal in code formatting before you start, and keep code blocks out of any rewriting tool entirely.
I keep the docs in Markdown and only ever paste the prose between code fences into a rewriter. It’s tedious for long pages. It is also the step that prevents broken instructions.
The README intro
Before (AI draft):
QueueKit is a powerful, flexible and developer-friendly job queue library designed to simplify background processing in Node.js applications. With its intuitive API and comprehensive feature set, QueueKit enables developers to efficiently manage asynchronous tasks at scale.
After:
QueueKit runs background jobs in Node.js using Redis. You define a job as an async function, push it onto a queue, and a worker process picks it up. Retries, delays and rate limits are built in.
The rewrite drops every adjective that can’t be verified (powerful, flexible, intuitive, comprehensive) and replaces them with three facts: what it runs on, how you use it, and what’s included. A reader can decide in one paragraph whether to keep going.
When I Humanize ai drafts like this one, I run only the intro paragraph through a humanizer in a professional style first, then make a second manual pass that adds the facts the tool can’t know (Redis, the async function model). The tool handles rhythm and strips the boilerplate phrasing. I handle accuracy. Splitting the work that way is faster than doing either half alone.
API reference descriptions
Generated reference docs tend to restate the function name in sentence form and then pad.
Before:
retry(job, options): This method is used to retry a job. It takes a job and an options object as parameters and allows you to configure the retry behavior according to your specific needs.
After:
retry(job, options): Re-queues a failed job. Pass { attempts: 3, backoff: 'exponential' } to retry up to three times with growing delays. Throws JobNotFailedError if the job hasn’t failed.
Three changes. A verb that says what actually happens (“re-queues”). An example options object, since that’s what the reader wants to copy. And the error case, which AI drafts almost always omit because the model wasn’t told about it.
Reference docs usually don’t need a humanizer at all. They need specifics, which come from reading the code or the tests. If the generated description says “allows you to configure the retry behavior according to your specific needs,” that’s a sign the model didn’t know the options, and neither will your reader.
Tutorials and guides
Tutorials are where AI voice is most obvious and where humanizing helps most, because they’re long stretches of explanatory prose.
Before:
In this step, we will configure the worker. It is important to note that the worker must be running in order for jobs to be processed. Additionally, you may wan
AI is useful for documentation. It’s fast at producing a first pass of an API reference from function signatures, decent at turning a Slack thread into a troubleshooting entry, and tireless about writing the boring parts nobody volunteers for. The problem is the voice. Model-written docs are padded, oddly enthusiastic, and full of hedges in the places where a reader needs certainty. Developers notice, and they start to distrust the content along with the tone.
This guide covers how to take AI-drafted docs and make them read like they came from an engineer who uses the software, with before and after examples from the parts of a docs site that suffer most.
Start by marking what must not change
Before any rewriting, by you or by a tool, identify the literal text. In technical docs, a surprising amount of content is not prose at all:
Code blocks and inline code
CLI commands and flags
Config keys, environment variable names, file paths
Version numbers, status codes, error strings
Anything a user might copy and paste
All of this must survive untouched. Paraphrasing tools treat unformatted text as ordinary words, so --dry-run written without backticks can come back as “a dry run,” and MAX_RETRIES can become “the maximum retries.” Wrap every literal in code formatting before you start, and keep code blocks out of any rewriting tool entirely.
I keep the docs in Markdown and only ever paste the prose between code fences into a rewriter. It’s tedious for long pages. It is also the step that prevents broken instructions.
The README intro
Before (AI draft):
QueueKit is a powerful, flexible and developer-friendly job queue library designed to simplify background processing in Node.js applications. With its intuitive API and comprehensive feature set, QueueKit enables developers to efficiently manage asynchronous tasks at scale.
After:
QueueKit runs background jobs in Node.js using Redis. You define a job as an async function, push it onto a queue, and a worker process picks it up. Retries, delays and rate limits are built in.
The rewrite drops every adjective that can’t be verified (powerful, flexible, intuitive, comprehensive) and replaces them with three facts: what it runs on, how you use it, and what’s included. A reader can decide in one paragraph whether to keep going.
When I Humanize ai drafts like this one, I run only the intro paragraph through a humanizer in a professional style first, then make a second manual pass that adds the facts the tool can’t know (Redis, the async function model). The tool handles rhythm and strips the boilerplate phrasing. I handle accuracy. Splitting the work that way is faster than doing either half alone.
API reference descriptions
Generated reference docs tend to restate the function name in sentence form and then pad.
Before:
retry(job, options): This method is used to retry a job. It takes a job and an options object as parameters and allows you to configure the retry behavior according to your specific needs.
After:
retry(job, options): Re-queues a failed job. Pass { attempts: 3, backoff: 'exponential' } to retry up to three times with growing delays. Throws JobNotFailedError if the job hasn’t failed.
Three changes. A verb that says what actually happens (“re-queues”). An example options object, since that’s what the reader wants to copy. And the error case, which AI drafts almost always omit because the model wasn’t told about it.
Reference docs usually don’t need a humanizer at all. They need specifics, which come from reading the code or the tests. If the generated description says “allows you to configure the retry behavior according to your specific needs,” that’s a sign the model didn’t know the options, and neither will your reader.
Tutorials and guides
Tutorials are where AI voice is most obvious and where humanizing helps most, because they’re long stretches of explanatory prose.
Before:
In this step, we will configure the worker. It is important to note that the worker must be running in order for jobs to be processed. Additionally, you may wan