Community discussion: Do you use a "template" to author your KB docs?


  • Spike

    In our case, it's organized primarily by the area (tabs) in our own system, plus other categories such as FAQ, Troubleshooting, etc.  I used the article name to help sort things logically.  Such as, within the setup area, there is a category called "Privileged" with different items within it.  So I title the articles "Privileged: item name1", "Privileged: Item name 2", etc.  

    See screenshot attached to give you some idea. 

  • Spike

    Otherwise, for the articles themselves, the format is dictated by the content really.  I try to stick to very simple content, bullet points instead of wordy paragraphs, and I include screen shots whenever possible to help the reader to link the instructions with our system screens.  

  • Andrea Saez

    No particular "template", but I also try to avoid long paragraphs. Bullet points and simple, straight-forward explanations. I try not to include way too many images, as the product is in constant change and it becomes tedious and harder to maintain, so I make it a point to write everything as simple enough so that images won't be as necessary.

  • Justin Graves

    I wish zd had a template feature for kb docs.  That would be great.  For now, I just use a variety of fonts to set sections apart and make them easier to read.  I use a block quote at the top of articles to alert folks when I make an update to an article.  I only use screenshots when absolutely necessary (and usually only with end-user facing articles, not ones for our agents).  

    Here you can see the formatting on one of my better kb articles.  Now I just need to go back and redo all of the other articles in my spare time... right.


  • Andrew J

    Being able to use a template would be great for getting suggestions from other agents, I think many of us would have totally different needs.  I am thinking that something like a ticket form would make this an easier thing to structure.  But would also need to be fully editable in the final version...

    This would be an example for 

    Title: Using your head

    Article Type:  Suggestion

    Related Product: KBR Plus


    Vini vidi vici!


  • Andrea Saez

    Another trip:

    • Bullet points, always

    • h2 tags. Remember SEO.

  • KirkFahlberg

    Yes, core two templates are -

    • PERC (problem, environment, resolution, cause) for issues

    • Question - Answer - Overview for FAQ's

    Lists can be in bullets, directions in numbered and lettered steps. The other "template" is direction and monitoring - each article should be a short solution to 1 core issue.


  • Jennifer Rowe

    Kirk, thanks for sharing! Can you attach screenshots so we can see your "template?" That would be awesome. Thanks.

  • Wim Casier

    I try to work with same lay out for all my articles a template would be most welcome! I see a template as a form where i can choose what article needs what information. Fill in the form and publish as an article...(wishfull thinking)

    ex. Category Reports needs:

    1. Title

    body text

    1. Title

    body text and bullets

    1. Title


    1. Title

    body text 

    1. Attachement
  • KirkFahlberg

    The PERC template I mentioned is based on the KCS Article Structure recommendation that is on Page 20 of the freely available guide - (attached).  Using Problem instead of Issue allowed it to be a mnemonic device - The PERC's of a good Knowledge article.  

    KCS Recommends

    • Issue (sometimes called symptom, question or problem)—the situation in the customer's words—what are they trying to do or what is not working?
    • Environment—what products does the user have (platform, products, releases)? How is it configured? Has anything in the environment changed recently?
    • Resolution (sometime called the fix or answer)—the answer to the question or the steps required to resolve the issue.
    • Cause— the underlying source of the issue. (optional, typically only valuable for problems or defects)
    • Metadata—attributes or information about the article such as the article state, the date created, number

    *PRC Template - *has become a shortened version as our Knowledge is separated into Product Categories (indirectly allowing the Environment to be answered)

    • Problem - Describe problem and try to use the words of the client.
    • Resolution - These are the steps to resolve 
    • Cause – What scenario caused or may have caused the issue
    • Labels - Keywords, Metadata - Additional words that relate to the article in question. Quite often terms that may be used by clients to describe the same thing - such as Remit, ERA, EOB, EOP. By reviewing Search Analytics/google analytics, add additional Labels as necessary.

    In regards to the Other format I mentioned Question, Answer and Overview helped to provide a level of Feature Function / How Do I options to our Knowledgebase.

    Question - Phrase the question in the customers terms if at all possible

    Answer - answer :-)

    Overview - Put in additional context, add in other keywords, phrases or variants of terms to increase findability

    Labels - Additional words that relate to the article in question. Quite often terms that may be used by clients to describe the same thing - such as Remit, ERA, EOB, EOP. By reviewing Search Analytics/google analytics, add additional Labels as necessary.

    The Core Ten Commandments of Article Creation

    1. Thou shall not create a duplicate
    2. Thou shall maintain the context of the customer
    3. Thou shall remember the audience
    4. Thou shall not reference a customer, patient nor incident
    5. Instructions shall be numbered steps, lists are bullets
    6. Product names shall be proper
    7. Graphics shall be kept small
    8. Section Headers in Bold
    9. Thou shall refrain from abbreviations and acronyms
    10. Thou shall use spellchecker

    I've also attached a collection of tips I have collected from other sites - Web Links are in the article to give credit where it is due.

    I have other guides here and there but I'll save finding those for a different rainy day.



  • Laura D.

    All of these are awesome, thanks everyone!

    Kirk - great collection of information, thanks for sharing!

  • Jennifer Rowe

    Kirk, thanks so much for providing the additional details. Super helpful.

  • Andrea Saez

    Hey guys,

    So I was thinking about this after the Community Moderator roundtable we had the other day. This might actually come in handy:

    Think of every new document as a flow chart. Try to write every step in a process within the flow chart, in as little words as possible.

    Process 1

    Process 2

    Process 3

    So on and so forth. The more concise you can make things, the better. Remember, people tend to not read big paragraphs ;)

  • Jennifer Rowe

    Good advice, Andrea. Thanks! It's definitely true that people don't read big paragraphs--and sometimes not even small paragraphs! :)

  • Roshni Champati

    Hi Jennifer, 

    Is there a way to add custom templates for KB articles in Zendesk?

  • Jennifer Rowe

    Hi Roshni,

    No, you can't add custom templates for KB articles. We keep a few "templates" in a private restricted section and ask authors to copy them as a starting point. We do this for our Fine Tuning series, for example.

    In the future, maybe an app can help solve this problem. 

    Hope that helps!



  • Kuljit Jagpal

    Good inputs here.  Has anyone integrated an app/CMS that incorporates template authoring and workflow for KB creation?  Thanks.

  • Julien Van de Casteele


    I see that the last comment here is quite old, so I was wondering if anyone had new feedback/best practices on this?

    Also, does Zendesk plan to allow for customizing the article and post creation forms

    With my organization we plan to use Zendesk mostly for its KB and community. We have identified different types of articles (how tos, best pratices, FAQ) and posts (lessons learned, ideas, questions) and their templates, because we've determined that different kinds of articles require different kind of information. We'd like to request information via different headings/question fields in the edition form. Unfortunately ZD does not offer to customize those fields.

    I am imagining something that is a bit similar to what we have with the tickets. Based on the type of article you'd like to write (which was selected via a drop-down menu), different fields load up asking various questions to be answered.

    This way we'd format the way different articles/posts are written and shared.

    At the moment, the only solution that I see is how it is done over here, via embedding a google form.... but not the best as then someone still needs to post it after..

    Let me know your thoughts?



  • Jessie Schutz

    Hey Julien!

    There haven't been a lot of changes here, but one thing that's different is the ability to post articles as Drafts.

    What I'm thinking is, you can create a series of "templates" - dummy articles that are formatted specifically for each type of content - and keep them saved as Drafts in your Help Center. Then your authors can just copy/paste the template into their new article, and all the formatting and required information will be accounted for.


Please sign in to leave a comment.

Powered by Zendesk