A Prompt That Finally Cleaned Up My Rambling Technical Drafts

A prompt was crafted to refine lengthy technical writings by focusing on clarity and brevity. For years, SolidJS tutorials faced criticism due to convoluted paragraphs and excessive filler phrases. Community members often revised the text, struggling with dense blocks of six sentences and scattered redundant expressions like "actually" or "simply put." Theo from T3.gg highlighted the issue by reconstructing a draft to showcase the excessive content. Grammarly identified typos but failed to address structural problems.

A single prompt was developed, integrating all past editing lessons. A rough draft, when fed into this prompt, produces a version that maintains reader engagement through concise structure. The prompt operates by treating each paragraph as a singular concept, imposing strict limits beyond the capabilities of tools like Grammarly. It also removes filler phrases that hinder readability without contributing meaning.

Assume the role of a technical editor specializing in developer tutorials. Edit the provided text according to the following guidelines:

1. Limit paragraphs to three sentences each, ensuring one idea per paragraph.
2. Eliminate all filler phrases, including "actually," "simply put," "in fact," "honestly," "basically," "just," "really," "literally," "obviously," "clearly," "needless to say," "it goes without saying," "as a matter of fact," and "for all intents and purposes."
3. Convert passive voice constructions into active verbs.
4. Preserve code blocks, headings, and technical terminology as originally written.
5. Insert blank lines between paragraphs to enhance readability.
6. Maintain the author's voice and technical conclusions, solely refining delivery.
7. Highlight any paragraph exceeding three sentences post-editing.

Output the revised text only.

When this prompt was applied to a 1,200-word document contrasting signals and observables, the initial version contained 14 paragraphs averaging 5.2 sentences. The revised version expanded to 23 paragraphs with an average of 2.1 sentences. The "flag" rule detected two overlooked sections, both requiring separate headers for clarity.

The list of filler words proved most effective in this process. These phrases may seem natural during writing but disrupt the flow for readers. Removing them compels a more direct and impactful expression. Last week, the prompt was tested on three RFCs from team members, resulting in documents shortened by 18-22% without sacrificing content. A developer described the outcome as "someone finally organizing my brain."

The sole drawback is its inability to correct poor architecture or flawed assumptions. For mechanical aspects like paragraphing, hedging, and passive voice, however, it surpasses human review efficiency.