Your opinion is request – Help Desk knowledge “Question and Answer” vs “Purpose and Procedure”

Hello,

The purpose of this blog post is to request collaboration from other technical writers after explaining an existing writing style that exists in a Knowledge Base that I manage, new practices that I have become aware of, and how I have planned on implementing the new practices.  I am also writing this to get a sense of collaboration from other Technical Writers that may be involved in Help Desk documentation to get their opinion and see what they do.

I work at an IT Help Desk and my responsibility is to maintain the documentation used by the Help Desk agents.  It is fast and exciting and I am always looking on ways to improve.

Most of the writing in the knowledge base have a format similar to the following:

——

Product – Problem

QUESTION

How do I do this with the product?

ANSWER

In order to do this with the product you must…

——

Recently in my Business Communications class I learned that Business Writing should be:

  • Purposeful
  • Persuasive
  • Economical (not too long)
  • Audience Oriented

I already know that my audience is a Help Desk agent primarily, a Subject Matter Expert secondarily, and Business Managers finally; however, you could argue that the current writing is more towards the audience of an end user.  Because of this I have decided to modify my writing just slightly to support the objectives set above from Business Writing standards as follows:

——

Product – Problem

PURPOSE

The purpose of this article is to describe to a Help Desk agent how they are to handle support request from a user asking how to [do this] with [the product].

PROCEDURE

Advise the user that in order to [do this] with [the product] they must,,,

——

The advantage to this is that I have more clearly defined my audience is and thus improves my use of pronouns throughout the rest of the article.  Furthermore SMEs and Management can be clear about the purpose as well.  On an additional note I believe that the “Question and Answer” format is better suited for a Level 0 / Self Service / End User Knowledge Base, and not a Help Desk Knowledge Base.

Let me know what you think and collaborate with me to let me know what your practices are or recommend for a Help Desk audience.

Thanks,
Sean W.

Comments

  1. Darren Gore

    Here’s some suggestions by editing what you’ve done

    [Product] – [Problem]

    AUDIENCE
    Help Desk Agents

    PURPOSE
    This article describes how to handle user support requests for how to [do this] with [product]

    PROCEDURE
    Instruct the user to do the following:
    [Step-table/numbered list instructions]

    Notes:

    • I added the heading AUDIENCE to immediately identify who this article is written for
    • I edited the text for economy and to give it a more active voice
  2. Darren Gore

    Here’s some suggestions by editing what you’ve done

    [Product] – [Problem]

    AUDIENCE
    Help Desk Agents

    PURPOSE
    This article describes how to handle user support requests for how to [do this] with [product]

    PROCEDURE
    Instruct the user to do the following:
    [Step-table/numbered list instructions]

    Notes:

    • I added the heading AUDIENCE to immediately identify who this article is written for
    • I edited the text for economy and to give it a more active voice

Your email address will not be published. Required fields are marked *