KB Article Draft Generator
1. Overview
This process converts a raw set of troubleshooting steps into a polished, formal Knowledge Base (KB) article. It organizes the information into a standard article format, makes the language clear and consistent, and prepares the article for review and publishing.
2. Business Value
- Consistent Documentation – Guarantees every article follows the same structure and tone, improving readability and reducing support effort.
- Efficiency – Turns raw troubleshooting notes into publish‑ready content in minutes rather than hours.
- Quality Assurance – Enforces a clear style and checklist, lowering the chance of missing steps or unclear instructions.
3. Operational Context
- When to run: Whenever a support team has a set of troubleshooting steps that need to become a reusable KB article.
- Who uses it: Documentation Specialists, support analysts, and content managers who are responsible for creating or updating KB content.
- Frequency: As often as new troubleshooting procedures are documented (e.g., daily, weekly, or per incident).
4. Inputs
The following items must be supplied for each individual article generation. All items are required unless an “Optional” label is shown.
| Name / Label | Type | Details Provided |
|---|
| Troubleshooting Steps Document | PDF file | The complete step‑by‑step troubleshooting guide (including any screenshots, notes, or pre‑requisite information). |
| Product / Service Name | Text | The name of the product or service the article is about (e.g., “Acme Laptop”). |
| Article Title | Text | The desired title for the KB article. If not supplied, the process will derive a title from the problem description. |
| Issue Summary | Text | A concise description of the problem being solved (one‑sentence overview). |
| Target Audience | Text | The intended readers (e.g., “End Users”, “IT Administrators”). |
| Version / Release | Text | The version, release, or model number relevant to the steps (e.g., “v1.2”). |
| Additional Context (optional) | Text | Any extra information, constraints, or known limitations that should be included (e.g., “requires admin rights”). |
All inputs must be provided as part of a single run of the process. Missing any required input will halt the process and generate a “Missing Information” flag for manual review.
5. Outputs
The process produces a ready‑to‑publish KB article in plain text format.
| Name / Label | Contents | Formatting Rules |
|---|
| KB Article Draft | A structured article containing the following sections in order: Title, Issue Summary, Prerequisites (if any), Step‑by‑Step Instructions, Additional Notes (optional), Version / Release, Target Audience, and Last Updated Date. | • Title in Title Case, bolded. |
| • Issue Summary as a single paragraph. | | |
| • Prerequisites and Additional Notes as bullet‑point lists (if present). | | |
| • Step‑by‑Step as a numbered list; each step starts with an imperative verb (e.g., “Open…”). | | |
| • Version / Release displayed as “Version: X”. | | |
| • Target Audience displayed as “Audience: X”. | | |
| • Last Updated Date in “Month Day, Year” format. | | |
| • Use a neutral and professional tone; avoid jargon, acronyms, or internal jargon. | | |
6. Detailed Plan & Execution Steps
- Collect Inputs: Verify that each required input (PDF, product name, title, etc.) is present and readable.
- Validate PDF: Open the Troubleshooting Steps Document and confirm it contains readable text and any images are clear.
- Extract Core Information:
- Identify the Issue Summary – either from the supplied summary or, if missing, from the first paragraph of the PDF.
- Identify any Prerequisite steps (e.g., “Make sure the device is powered on”).
- Extract each Step in order, preserving any sub‑steps as sub‑items.
- Capture any Additional Notes that appear as warnings, tips, or “Note” boxes.
- Create Title: Use the supplied Article Title; if absent, generate a title using “How to …” + Product Name + key problem phrase. Ensure Title Case and bold.
- Build Section – Issue Summary: Write a concise one‑sentence summary that explains what problem the article solves. Use simple language.
- Build Section – Prerequisites: If the PDF lists any prerequisites (e.g., “Ensure the device is powered on”), list them as bullet points; otherwise, leave the section out.
- Build Section – Step‑by‑Step Instructions:
- Convert each raw step into a sentence beginning with an action verb (e.g., “Open Settings”).
- Use numbered format (1., 2., …).
- If a step contains sub‑steps, number them 1.1, 1.2, etc.
- Ensure each instruction is concise (≤ 20 words) and includes only actions the user can perform.
- Build Section – Additional Notes: Include any “Tip”, “Warning”, or “Note” content from the PDF as bullet points.
- Add Version / Release: Insert “Version: X” line after the steps.
- Add Target Audience: Insert “Audience: X” line after the version.
- Add Last Updated Date: Insert the current date in “Month Day, Year” format (e.g., “July 15, 2025”).
- Apply Formatting Rules: Ensure bolded title, proper headings, and correct list formatting. Use a neutral and direct voice.
- Compile Final Draft: Assemble all sections into a single plain‑text document in the order defined.
- Quality Check: Run the validation checks (see Section 7) before finalizing.
- Output: Provide the completed KB Article Draft as plain text.
7. Validation & Quality Checks
- Presence Check: Ensure all required inputs are present; if not, halt and flag for manual review.
- PDF Readability: Confirm the PDF can be opened and the text is legible; if not, flag for manual review.
- Title Presence: Verify the article title is non‑empty; if missing, use auto‑generated title.
- Step Count: Ensure there is at least one numbered step; if none, flag for manual review.
- Formatting Check:
- Title must be bolded and Title Case.
- Steps must be numbered and start with an imperative verb.
- No blank lines between items within a list.
- Language Consistency: Verify tone is neutral and professional; no slang, profanity, or internal jargon.
- Version & Audience: Both fields must be present; if missing, insert “Version: Not Specified” or “Audience: General Users”.
- Date Accuracy: Ensure the “Last Updated Date” matches the execution date.
- Final Review: Read the draft from start to finish to confirm logical flow and completeness.
If any check fails, the process stops and creates a “Error – <description>” flag for manual review. No draft is produced until all checks pass.
8. Special Rules / Edge Cases
- Missing Issue Summary: Use the first sentence of the first step as a fallback summary.
- Missing Prerequisites: If no explicit prerequisites are listed, omit the section entirely.
- Sub‑steps: If a step includes sub‑steps (e.g., “1.1”, “1.2”), keep the hierarchical numbering.
- Version Not Provided: Insert “Version: Not Specified”.
- Target Audience Not Provided: Default to “Audience: General Users”.
- Non‑English Characters: Preserve them as they appear; do not transliterate.
- Image References: If the PDF contains images, note them in the Additional Notes as “(See attached image for reference)”. No actual images are generated.
- Lengthy Step: If a step exceeds 30 words, split it into two steps, preserving order.
- Duplicate Steps: If the same step appears multiple times, keep only the first occurrence.
- Ambiguous Language: When a step is ambiguous, retain the original wording, but add a note “(Clarify if possible)”.
- Critical Warning: Any step containing “do not”, “never”, or “must not” is flagged for a second review before publishing.
- Failure to Generate: If any required input is missing or a validation fails, generate a short error notice: “Error: <brief description of missing/invalid item> – Manual review required.”
9. Example
Input
- Troubleshooting Steps Document (PDF):
Problem: Unable to connect to Wi‑Fi on an Acme Laptop.
Prerequisite: Battery must be at least 20% charge.
1. Open the Settings app.
2. Tap on “Network & Internet”.
3. Select “Wi‑Fi”.
4. Turn the Wi‑Fi toggle on.
5. Choose “CompanyNetwork” from the list.
6. Enter the password “Pass1234” and click “Connect”.
Note: If the network does not appear, click “Refresh”.
- Product / Service Name: “Acme Laptop”
- Article Title: None provided
- Issue Summary: “User cannot connect to corporate Wi‑Fi.”
- Target Audience: “End Users”
- Version / Release: “v1.2”
- Additional Context: “The laptop must be running Windows 10.”
Output – KB Article Draft (Plain Text)
Title: How to Connect to Wi‑Fi on an Acme Laptop
Issue Summary
User cannot connect to corporate Wi‑Fi.
Prerequisites
- Battery must be at least 20% charge.
Step‑by‑Step Instructions
- Open the Settings app.
- Tap Network & Internet.
- Select Wi‑Fi.
- Turn the Wi‑Fi toggle on.
- Choose CompanyNetwork from the list.
- Enter the password Pass1234 and click Connect.
- If the network does not appear, click Refresh. (Note: If the network does not appear, click “Refresh”.)
Version: v1.2
Audience: End Users
Last Updated: August 11, 2025
Appendix A – FAQ
Q1: What if the troubleshooting document is missing a prerequisite?
A: The process will omit the Prerequisites section. If you know a prerequisite, add it manually in the Additional Notes section.
Q2: How do I handle an error message that is not a step?
A: Place the message in the Additional Notes section, prefixed with “Note:” or “Warning:”.
Q3: Can I add screenshots to the article?
A: This SOP produces plain‑text output. Mention the existence of an image in Additional Notes (e.g., “(See screenshot 1 for the Wi‑Fi toggle).”
Q4: What if the steps are out of order?
A: The process assumes steps are already ordered in the source document. If they appear out of order, reorganise them before running the process.
Q5: What if the user needs a different language version?
A: This process does not perform translation. Provide the translation as a separate input to a separate run of the process.
Q6: How is “Last Updated” determined?
A: The date is set automatically to the current date at the time of running the SOP.
Q7: Should I include internal product IDs?
A: No. The article should only contain user‑facing information. Remove all internal IDs or references.
Q8: What if the PDF is scanned and not searchable?
A: The process requires readable text. If the PDF is scanned, the process will halt and request a readable version.
Q9: How should I phrase a step that requires user input?
A: Use a direct verb plus description, e.g., “Enter the password Pass1234 and click Connect.”
Q10: What if the article must be in a specific style (e.g., “All caps headings”)?
A: The SOP uses Title Case for the title and bolded. If a different style is needed, modify the Formatting Rules in Section 5.
Q11: How are “Tips” handled?
A: Tips appear as bullet points under Additional Notes with the prefix “Tip:”.
Q12: What should I do if the Target Audience is unknown?
A: The default is “General Users”. Update later if you have a more specific audience.
Q13: Can the process add a “Troubleshooting” section?
A: No. The SOP produces only the sections listed in the Outputs. Any extra sections must be added manually after the draft is generated.
Q14: What if a step contains a link?
A: Include the link in parentheses after the relevant instruction, e.g., “Visit the support site (https://support.acme.com).”
Q15: How can I ensure the article meets corporate branding?
A: Verify that the final draft is reviewed against the corporate style guide (see Appendix C) before publishing.
Appendix B – Glossary
| Term | Definition |
|---|
| KB (Knowledge Base) | A repository of documented information used to support customers and staff. |
| Article | A single entry in the Knowledge Base that contains a problem description and solution steps. |
| Prerequisite | A condition that must be true before the steps can be performed (e.g., “Battery at least 20%”). |
| Step‑by‑Step Instruction | A numbered directive that a user follows to solve a problem. |
| Target Audience | The group of users for whom the article is written (e.g., End Users, IT Administrators). |
| Version / Release | The specific product version, release number, or model to which the instructions apply. |
| Additional Note | Supplemental information such as warnings, tips, or clarifications. |
| Last Updated | The date on which the article was most recently revised. |
| Verb (imperative) | An action word that starts a step (e.g., “Open”, “Click”, “Enter”). |
| Bold | Text formatting style used for the article title and important headings. |
| Title Case | Capitalization format where the first letter of most words is capitalized (e.g., “How to Reset Password”). |
Appendix C – Reference Materials
C1 – KB Article Structure Template
- Title – Bold, Title Case, centered or left‑aligned.
- Issue Summary – One paragraph (50–100 words) describing the problem the article resolves.
- Prerequisites (optional) – Bulleted list.
- Step‑by‑Step Instructions – Numbered list; each step begins with a strong verb. Sub‑steps use a decimal format (1.1, 1.2).
- Additional Notes (optional) – Bulleted list, each preceded by “Tip:”, “Note:”, or “Warning:”.
- Version / Release – “Version: X”.
- Target Audience – “Audience: X”.
- Last Updated – “Month Day, Year”.
C2 – Style Guide
| Aspect | Guidelines |
|---|
| Tone | Neutral and professional. Avoid slang, humor, or colloquialisms. |
| Voice | Active voice; start each instruction with an imperative verb (e.g., “Open”, “Select”). |
| Sentence Length | ≤ 20 words per instruction. Keep sentences short and clear. |
| Word Choice | Use plain English. Avoid technical jargon unless required, then define the term in the first occurrence (e.g., “Wi‑Fi (wireless network)”). |
| Capitalization | Title Case for titles; sentence case for body text. |
| Punctuation | End each step with a period; avoid exclamation points. |
| Numbers | Use Arabic numerals (1, 2, 3) for steps; use numbers for version and dates. |
| Formatting | Bold only for the title and sub‑headings; do not bold step text. |
| Links | Include the full URL in parentheses after the relevant text. |
| Images | Mention images in brackets (e.g., “(see screenshot 1)”). Do not embed images in text output. |
| Pronouns | Use “you” when addressing the user (e.g., “You should...”). |
| Consistency | Use the same phrasing for repeated actions (e.g., always “Click” instead of “Press”). |
| Versioning | Always include “Version: X” after the steps, before the audience. |
| Date Format | “Month Day, Year” (e.g., “July 15, 2025”). |
| Grammar | Use present tense for instructions; keep grammar simple. |
| Error Handling | If an error condition is noted, place it in Additional Notes with “Warning:” prefix. |
C3 – Prohibited Content & Classification
- Personal Data: Do not include personal names, email addresses, phone numbers, or any personally identifiable information (PII) of customers or staff.
- Sensitive Business Information: Do not include internal passwords, network keys, or confidential configuration settings.
- Legal/Compliance Statements: Avoid making legal claims or guarantees. Add a disclaimer only if approved by legal.
- Copyrighted Material: Do not embed copyrighted text without permission. Use “Reference” tags if needed.
- Inappropriate Content: No profanity, offensive language, or discriminatory statements.
- Spamming: Do not include promotional language unrelated to the troubleshooting steps.
C4 – Detailed Examples of Proper Formatting
Example 1 – Correct Format
**Title: How to Reset a Forgotten Password in MyApp**
**Issue Summary**
Users cannot log in because they forgot their password.
**Prerequisites**
- A registered email address.
**Step‑by‑Step Instructions**
1. Open **MyApp** on the device.
2. Tap the **Forgot Password** link.
3. Enter your registered email address.
4. Click **Send Reset Link**.
5. Check your email inbox for the reset link.
6. Click the link in the email and follow the on‑screen instructions.
**Version: 2.5**
**Audience: End Users**
**Last Updated: August 11, 2025**
Example 2 – Incorrect (Missing Verb)
1. The settings screen is opened. (Incorrect)
Corrected
1. Open the Settings screen. (Correct)
Example 3 – Incorrect Use of Bullet in Step List
- 1. Open the Settings app. (Incorrect: bullet used instead of a numbered step)
Corrected
1. Open the Settings app.
Example 4 – Missing Version
**Version** (Missing value) – This will trigger a validation error.
Corrected
**Version: Not Specified**
C5 – Common Pitfalls & Remedies
| Pitfall | Symptom | Remedy |
|---|
| Missing Prerequisite | “Prerequisites” section appears empty or missing. | Ensure the PDF contains a clear “Prerequisite” section; otherwise, omit the section. |
| Step Not Starting with Verb | Step begins with “The” or “A”. | Edit step to start with an action verb. |
| Duplicate Steps | Same step appears more than once. | Remove duplicate, keep the first occurrence. |
| Long Step | > 30 words. | Split into two separate steps that preserve logical order. |
| Missing Version | “Version” line is empty. | Insert “Version: Not Specified” or supply proper version. |
| Invalid Date | Date not in “Month Day, Year” format. | Convert to proper format. |
| Use of “you” in a warning | “You should not…” appears in steps. | Move such statements to Additional Notes with “Warning:”. |
| Unclear Sub‑step | Sub‑steps not indented. | Use “1.1”, “1.2” format for sub‑steps. |
| Incorrect Capitalization | Title not in Title Case. | Adjust to Title Case (e.g., “How to Connect to Wi‑Fi on an Acme Laptop”). |
| Missing Target Audience | “Audience” line missing. | Insert “Audience: General Users” if unknown. |
| PDF Not Accessible | Cannot open PDF. | Provide a readable PDF. |
C6 – Template for Manual Editing (After SOP)
Title: [Your Title Here] (Bold, Title Case)
Issue Summary:
[One‑sentence summary of the problem.]
Prerequisites:
- [Prerequisite #1]
- [Prerequisite #2]
Step‑by‑Step Instructions
1. [Verb] [action].
2. …
3. ...
Additional Notes:
- Tip: [...]
- Warning: [...]
Version: [X]
Audience: [Target Audience]
Last Updated: [Month Day, Year]
Use this template for manual adjustments after the automatic generation. Ensure any additions adhere to the style guide and do not introduce prohibited content.
