About this sample

In this writing sample, I showcase my expertise in DITA (Darwin Information Type Architecture) technical writing style. DITA breaks content into modular 'Topics,' making them reusable and easy to maintain. I cover three types: Concept, Task, and Reference. In the first Concept article, I explain the Knowledge Centered Support (KCS) concept of 'Capturing in the Workflow.' Following that, the second Task article details the steps for 'Drafting an article while working on a support case.' Lastly, I provide a Reference article outlining how to use each field of a Support Article.

metadata

Audience
Customer Support Agents
Type
Help Article
Where
Sage, Yahoo

Technical Writing: DITA Samples

Knowledge Management
Technical Writing
created by | Randy Santamaria
Important:
Details in this work sample have been altered to preserve privacy, including the use of fictitious names and product information.

Capturing in the Workflow

In Knowledge Centered Support (KCS), capturing knowledge within the workflow is a critical aspect of the methodology. It involves seamlessly integrating knowledge capture into the interaction between the customer service agent and the customer.

The customer agent views the case details alongside the knowledge base window, allowing them to search for articles. If they don't find one, they draft an article from the same window. The "Draft article" page presents the template for "Support Articles," guiding the agent on what and where to capture information.

Why we capture in the workflow:

  • Knowledge is captured when needed, reducing the risk of losing or forgetting information.
  • Captured knowledge in a Support Article template is easily accessible to other agents via search, even if it's still in draft.
  • Knowing what drafts other agents are working on promotes collaboration, especially when their customer’s issues are similar.
  • After agents capture a problem and its resolution in the knowledge article, they can send it to Technical Writers for technical and editorial review. Once published, the article becomes accessible to customers experiencing similar issues, expediting the availability of our knowledge where it's needed.

Effective knowledge capture in the workflow requires:

  • Accessible tools and platforms that facilitate easy documentation and sharing of knowledge.
  • Clear guidelines and best practices for capturing and formatting knowledge, ensuring consistency and quality across documentation.
  • Training and support for employees to encourage active participation in knowledge capture activities and reinforce the importance of their contributions.
  • Regular review and validation of captured knowledge to identify gaps, inaccuracies, or outdated information.

By embedding knowledge capture into the workflow, organizations can leverage the collective expertise of their employees to continuously improve support processes, enhance customer experiences, and drive organizational success.

Related resources:

DITA Code snippet

Here is a sample of what the XML might look like according to DITA standards.

‍

Sample XML structure
created by | Randy Santamaria

Drafting an article while working on a support case

Draft an article using the integrated knowledge base application in the Salesforce Service Console. Search the knowledge base first before drafting an article. Draft an article if you find no articles that help solve the issue.

Drafting an article from a Service Console case record will automatically link your draft article to the case for reporting purposes.

When an article is linked to a case record, it can be assumed that the article contributed to solving the case.

Prerequisites:

  • Salesforce Service Console license
  • Salesforce Permission Set: KB Author
  • Knowledge base profile: Author

To draft an article from the Salesforce Service Console:

  1. Open Service Console.
  2. Open a case record.
    ‍Result: the case record opens, and the knowledge base window shows search results using the case Description as the search query.
  3. Click “Draft” in the Knowledgebase window.
    ‍Result: the Draft article window displays.
    ‍Result: “Support Article” template type is selected.
    ‍Result: Case metadata automatically apply to the article.
  4. Fill-in the fields of the article as you interact with the customer.
  5. Keep Status set to “Draft”.
  6. Click “Save”.
    ‍Result: the article saves.
    ‍Result: the article is searchable by other support agents in the knowledge base.
  7. To submit the article to Technical Writers for review, change the status to “Review” and click “Save”.

Related resources:

DITA code snippet

Here is a sample of what the XML might look like according to DITA standards.

‍

created by | Randy Santamaria

Writing in Support Article Fields

The Support Article template type has unique fields to compared to other articles. This reference is a guide on how to properly populate these fields.

Support Article fields

Support Article Field Required? Objective Tips Why it matters
Title Yes Craft a concise yet descriptive title. Include the main component or feature and the issue type (e.g., "Login Failure - Password Reset Error"). A clear title ensures quick identification and categorization of the issue.
Keywords Yes List relevant keywords associated with the issue. List relevant keywords associated with the issue. Keywords enhance searchability within the knowledge base, making it easier to find and solve similar issues.
Description (Symptoms) Yes Provide a clear, concise summary of the issue from the customer's perspective. Note the symptoms the customer is experiencing, using their own words when possible. Avoid technical jargon if it obscures understanding. A well-documented summary helps in diagnosing the problem and identifying patterns over time.
Steps to Reproduce No Outline the steps needed to replicate the issue. Number each step and include any specific conditions under which the issue occurs. Replicating the issue is crucial for understanding its nature and finding a resolution.
Environment or Setup Context No Detail the customer’s environment or setup where the issue occurs. Include information like software version, devices used, network conditions, or any unique configurations. Environmental factors often influence the occurrence and nature of technical issues.
Cause No Identify and document the root cause of the issue, if known. Be as specific as possible, differentiating between confirmed causes and potential contributing factors. Understanding the cause is essential for resolving the current issue and preventing future occurrences.
Resolution No Describe the solution or workaround provided to the customer. Include step-by-step resolution steps and any alternative solutions offered. A clearly documented resolution aids in faster resolution of similar issues in the future and improves customer satisfaction.
Internal Comments No Note any observations, insights, or follow-up actions required. The customer can't see this field. Mention any collaboration with other teams, escalation details, or customer feedback. Internal comments provide context and additional insights for future reference, helping in continuous learning and process improvement.
Categories Yes Categorize the issue based on predefined criteria (e.g., software, hardware, user error). Choose the most relevant categories that fit the issue. More than one category may apply. Proper categorization helps in organizing the knowledge base and streamlining the resolution process for similar issues.

Good and bad examples of using each field

Title

  • Good Example: "Error 404 - Page Not Found When Accessing Account Settings"
  • Bad Example: "Problem with Account"

Keywords

  • Good Example: "Error 404, Page Not Found, Account Settings"
  • Bad Example: "Problem, Account Issue"

Description (Symptoms)

  • Good Example: "Customers are unable to access their account settings page and receive a 'Page Not Found' error message."
  • Bad Example: "Customers reporting issues with account"

Steps to Reproduce

  • Good Example:
    1. Log in to the account.
    2. Navigate to the settings page.
    3. Click on "Account Settings".
    4. Observe the error message displayed.
  • Bad Example: "Try to access account settings."

Environment or Setup Context

  • Good Example: "Customers using Chrome browser version 98.0.4758.102 on Windows 10."
  • Bad Example: "Customer on a computer"

Cause

  • Good Example: "Issue caused by recent update to account settings module, conflicting with certain browser configurations."
  • Bad Example: "Not sure what's causing the problem."

Resolution

  • Good Example: "Provided workaround by clearing browser cache and cookies, then accessing account settings through an incognito window."
  • Bad Example: "Told customer to try again later."

Internal Comments

  • Good Example: "Escalated the issue to the development team for further investigation."
  • Bad Example: "Noted the problem."

Categories

  • Good Example: "Software Issue, Account Management"
  • Bad Example: "General"

‍

rndy.io | Randy Santamaria