Q1. For which product you created software documentation?
Q2. Email (xyz) and name different?
Q3. Have you worked on Intro?
Q4. Could you tell me some tools you have used for authoring, structuring, publishing, illustrating, or repositories?
A. Authoring tools: MS Word and madcap flare
B. Structuring tools: Madcap Flare
C. Publishing: Confluence, sharepoint and Madcap Flare
D. Illustrating: MS Visio, greenshot
E. Repository: Confluence and madcap flare
Q5. Have you any experience with Madcap Flare?
Q6. Can you briefly explain the difference between structured content and unstructured content?
A: The key difference between structured content and unstructured content lies in how the information is organized, stored, and managed.
Structured Content
Definition: Content that follows a predefined format with metadata, making it easily searchable, reusable, and adaptable for multiple outputs.
Characteristics:
- Organized using XML, DITA, or JSON.
- Modular, reusable, and component-based.
- Uses semantic tagging (e.g., <title>, <para>, <table>).
- Enables automation, filtering, and multi-channel publishing.
- Managed in Component Content Management Systems (CCMS).
Example:
- A DITA-based knowledge base article in a CCMS.
- API documentation stored in JSON or XML.
- Technical manuals authored in structured authoring tools like Oxygen XML Editor or FrameMaker.
Unstructured Content
Definition: Content that lacks a predefined structure, making it harder to search, reuse, or repurpose.
Characteristics:
- Commonly done in word processors like MS Word, Google Docs.
- Lacks semantic tagging and modular organization.
- Formatting is applied manually (bold, italics, headings).
- Less efficient for automation and multi-channel publishing.
Example:
- A PDF user guide created in Microsoft Word.
- An email with troubleshooting steps.
- A blog post without metadata or structured tagging.
Why It Matters in ITSM Documentation
Structured content is crucial for ITSM documentation because it allows:
- Easy updates across multiple documents.
- Single-sourcing for different formats (PDF, HTML, chatbot responses).
- Integration with ITSM tools like ServiceNow Knowledge Management.
Unstructured content is less efficient for ITSM documentation because:
- It requires more manual effort to update.
- It’s harder to integrate with automation tools.
- Searching and filtering content is more challenging.
In JSM, structured and unstructured content have different positions for knowledge management and ITSM documentation.
Structured Content in JSM
Where it Exists:
- Confluence Knowledge Base (when integrated with JSM).
- Jira Custom Fields (structured data in tickets).
- Automation Rules & Workflows (predefined logic).
Characteristics:
- Uses predefined templates for articles and issues.
- This includes metadata, labels, and structured fields to enable searching and automation.
- Supports structured authoring in Confluence- macros, templates, and metadata.
- Facilitates automation and reporting (e.g., structured ticket data for SLA tracking).
Example:
- A structured knowledge base article in Confluence linked to a JSM request.
- A Jira ticket with custom fields like “Incident Type,” “Priority,” and “Affected Service.”
- Pre-configured automated rules that escalate tickets based on structured data.
- Unstructured Content in JSM
Where it Exists:
- Free-text descriptions in tickets.
- Manually written knowledge base articles without structured templates.
- User comments and chat logs.
Characteristics:
- Lacks metadata, making searchability and automation harder.
- Manually formatted without consistent tagging.
- Difficult to reuse across different channels.
Example:
A Jira ticket with an unclear description:
“System not working. Please fix ASAP!”
(Lacks structured details like error codes or affected services.)
A manually written knowledge base article with inconsistent formatting.
A customer comment in a ticket:
“I restarted my computer, but the issue persists. What should I do?”
Why Structured Content Matters in JSM
- Improves Knowledge Searchability: Structured knowledge base articles help agents find solutions faster.
- Enhances Automation: Structured tickets allow automation rules to trigger appropriate workflows.
- Supports Multi-Channel Publishing: Structured content can be reused across portals, chatbots, and self-service channels.
Structuring Knowledge Base Articles in Confluence for Jira Service Management (JSM)
A well-structured knowledge base (KB) in Confluence, when integrated with JSM, improves self-service, ticket deflection, and agent efficiency. Here’s how to structure KB articles effectively.
1. Use a Standardized Article Template
Consistent structure allows easy readability, reusability, and searchability. Confluence allows you to create templates for different article types (e.g., troubleshooting, FAQs, procedures).
Example: Troubleshooting Article Template
Section Content
Title Clear, concise problem statement (e.g., “How to Resolve VPN Connection Issues”)
Summary Brief description of the issue and resolution
Symptoms Bulleted list of error messages, affected systems, or common behaviors
Cause If known, describe the root cause (e.g., network outage, misconfiguration)
Resolution Steps Step-by-step instructions with screenshots or links
Related Articles Links to other KB articles or documentation
Tags/Labels Metadata for better searchability (e.g., VPN, network issue, troubleshooting)
✅ Tip: Use Confluence macros like Page Properties, Excerpt, and Table of Contents to enhance organization.
2. Optimize for JSM Search & Ticket Deflection
- When a user submits a JSM request, the system suggests relevant KB articles. To improve accuracy:
- Use sufficient keywords in the title and the first paragraph.
- Add structured labels/tags that match JSM request types.
- Format articles consistently using headings, tables, and bullet points.
- Include common error messages to match user queries.
🔍 Example (for VPN issues):
Instead of: “My VPN is broken”
Use: “VPN Connection Fails with Error Code 809 in Windows 10”
3. Use Metadata & Macros for Organization
- Labels: Helps categorize articles for quick filtering. (e.g., incident, FAQ, troubleshooting)
- Page Properties Report Macro: Creates a dynamic index of KB articles.
- Include Macro: Reuse common instructions across multiple pages.
- Status Macro: Show article status (Draft, Published, Deprecated).
4. Automate KB Maintenance
- Set Expiry Reminders: Use Confluence’s reminders to review outdated articles.
- Track Usage Metrics: Monitor views, likes, and feedback to improve content.
- Link KB Articles to Jira Issues: Ensure articles appear in agent workflows.
5. Connect KB Articles to JSM Workflows
- Enable “Use Confluence for Knowledge Base” in JSM settings.
- Set up Smart Links to attach relevant KB articles to ticket categories.
- Use Jira Automation to suggest articles based on ticket fields.
Example of a Well-Structured KB Article in Confluence
📌 Summary: This article explains how to fix VPN connection failures caused by firewall settings and network issues.
Symptoms:
VPN fails to connect with Error Code 809.
Cause:
Firewall is blocking VPN traffic.
Windows registry settings prevent VPN connections.
Resolution Steps:
Check Firewall Rules:
Open Windows Defender Firewall.
Allow VPN-related applications through the firewall.
Modify Windows Registry:
Open regedit.exe and navigate to:
sql
CopyEdit
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\PolicyAgent
Add a new DWORD AssumeUDPEncapsulationContextOnSendRule and set it to 2.
Restart the VPN Service:
Open Command Prompt as Admin.
Run: net stop RasMan && net start RasMan
Retry VPN Connection.
Related Articles:
How to Configure VPN in Windows 10
Common VPN Errors and Fixes
🕒 Last Updated: Feb 2025 | 🔖 Tags: VPN, network issue, Windows 10
Q7. What Style Guide do you follow?
Q8: Can you recall some do’s and don’ts in the MSTP style Guide?
Example: punctuation!
Q9. Can you explain the reuse concept in oxygen XML tools?
A: You can explain in terms of Madcap Flare.
Q10. Any thoughts on versioning? [DITA}
Q11. Repository?
———————————————————————————————————————————–