[Prompt] - Evaluating Drafts based on Clarity, Conciseness, and Consistency
Creating effective engineering documentation relies on several foundational principles that guide content creation and organization. Adhering to these principles ensures that documentation is not only accurate but also highly usable and impactful.
Understanding Your Audience and Purpose
Before any documentation is drafted, a clear understanding of its purpose and intended audience is paramount. The purpose can vary widely, from explaining a complex system to new team members, providing detailed instructions for equipment maintenance, or outlining critical safety procedures. The audience, in turn, dictates the language, level of detail, and specific content that should be included.
Clarity, Conciseness, and Consistency
These three principles are synergistic, forming the bedrock of high-quality technical writing.
Clarity: Documentation must be easy to understand. This involves using simple, plain language and avoiding unnecessary jargon unless it is clearly defined within the document. Complex information should be broken down into smaller, digestible chunks, often utilizing headings, subheadings, and bullet points. Employing active voice makes sentences more concise and direct, enhancing readability.
Conciseness: Get straight to the point. Eliminate superfluous words and redundancies, and use bullet points or lists to facilitate quick scanning and focus on essential details. Keeping paragraphs to four to six lines and sentences to 10-20 words significantly improves readability.
Consistency: Maintain a uniform tone, writing style, formatting (such as fonts, headings, and bullet points), and standardized terminology throughout the document and across the entire documentation suite. Leveraging established guides like Google's developer documentation style guide or the Microsoft Writing Style Guide is recommended.
Prompt
You are an expert technical editor. Review the following documentation draft with a focus on clarity, conciseness, and consistency. Provide specific, actionable feedback in each category. 1. Clarity - Identify any undefined jargon, ambiguous language, or overly complex sentences. - Suggest simpler alternatives or improved structure for better understanding. 2. Conciseness - Highlight redundant phrases, wordy constructions, or overly long paragraphs. - Recommend where bullet points or lists can be used to streamline information. - Suggest revisions to shorten or tighten the content without losing meaning. 3. Consistency - Check for inconsistent tone, formatting (e.g., headings, bullets), or terminology. - Focus especially on consistent use of key terms like [specific terms comma separated] - Point out formatting mismatches or terminological drift, and propose standardized alternatives. Documentation Draft: [Paste your documentation draft here]How to use
Replace [specific terms] with important terms from your documentation (e.g., product names, feature terms, or domain-specific vocabulary).
Paste your draft content where indicated.
Run the full prompt in ChatGPT or your preferred LLM to receive a structured editorial review based on clarity, conciseness, and consistency.
Ideal for refining technical documentation, user guides, knowledge base articles, and internal docs.
Important Note: AI as Your Co-pilot
AI is a powerful assistant, a "co-pilot," but it is not a replacement for human expertise, critical thinking, or oversight. Always review, refine, and fact-check AI-generated content. Your understanding of the project, audience, and technical accuracy remains paramount. Use AI to automate repetitive tasks, ensure consistency, and generate initial drafts, freeing you to focus on strategic planning and complex problem-solving.