Knowledge Base discussions

Article summary workshop

  1. Thanks to Bram for putting all of this information together.

    tl;dr
    Remember classified ads? Write it like that.


    Best Practices

    • Summary not affect Google PageRank, but Google will highlight matching keyword on the description.
    • Length: ~155 characters. Search engine cut off anything longer than 160 characters.
    • Write it using alphanumeric characters only. Quotes ("") will get cut off.
    • Don't use wiki markup in the summary.
    • A lot of our name recommendations could take a lot of space to write. If they take a lot of space, the long explanation should go into the article summary field, not the title.


    Examples

    Article Name: Permissions Manager - Give certain websites the ability to store passwords, set cookies and more
    Summary: How to give certain websites the ability to store passwords, set cookies, share location, open pop-up windows and keep online storage.

    Article Name: Firefox says it's just updated every time it starts - how to fix
    Summary: The What’s New tab keeps appearing after you update Firefox instead of your home page. We'll show you how to reset your home page.


    Exercise

    Reply with summary suggestions for the articles below.

    Thanks to Bram for putting all of this information together. '''tl;dr'''<br> Remember classified ads? Write it like that. ==Best Practices== *Summary not affect Google PageRank, but Google will highlight matching keyword on the description. *Length: ~155 characters. Search engine cut off anything longer than 160 characters. *Write it using alphanumeric characters only. Quotes ("") will get cut off. *Don't use wiki markup in the summary. *A lot of our name recommendations could take a lot of space to write. If they take a lot of space, the long explanation should go into the article summary field, not the title. ==Examples== '''Article Name:''' [[How do I manage website permissions?]]<br> '''Summary:''' How to give certain websites the ability to store passwords, set cookies, share location, open pop-up windows and keep online storage. '''Article Name:''' [[Firefox has just updated tab shows each time you start Firefox]]<br> '''Summary:''' The What’s New tab keeps appearing after you update Firefox instead of your home page. We'll show you how to reset your home page. ==Exercise== Reply with summary suggestions for the articles below. *[[Firefox makes unrequested connections]] *[[Firewalls]] *[[JavaScript]]
  2. This looks great guys! A couple things that I wanted to add to what you've written above.

    The article summary along with the title are the only things that the user has to judge whether an article will answer their question or not. I refer to this as "User Confidence" and it directly impacts click thru. Even if we serve the correct article at the top of the search results list, the user needs to make the mental connection between the search query and the results we display for them to click thru. For articles that are more troubleshooting in nature, we should put the symptoms in the summary as that is likely what the user will search. Verdi gave a great example of a troubleshooting article above. If an article is more of a general information type article we should use the summary field to list the topics covered in the article.

    Here is an example search: Open window in new tab

    Now take a look at the fourth result in the list. Here is what you'll see:
    Article Name: Options Window - Tabs Panel
    Summary: This document explains all of the preferences available in the Tabs panel of the Preferences window of Mozilla Firefox. For other panels, see Preferences window.

    As an end user, I've got no way of connecting the search that I've entered with the information displayed for this article so I won't click on it.

    It would be far more enticing if it looked something like this:
    Article Name: Tab Options and Behavior
    Summary: The Options Window - Tabs Panel allows you to customize tab behaviors such as opening new windows in tabs, warnings for opening/closing multiple tabs, displaying the tab bar at all times, and switching to new tabs immediately.

    You can really see how little information we are giving in search results if you do a search for options. It's probably not a very common search, but this illustrates the point as most of the summaries simply repeat the title of the document.

    One last thing to mention is that we should always give search higher priority than browse navigation when we are naming our documents and writing summaries. Why you ask? Because we can manually change the title of a document to fit our task based navigation and we won't be showing the summary! We don't have the luxury to change the titles in search results. This is something that can be done with best bets and tailored searches, but that is a conversation for a different thread!

    This looks great guys! A couple things that I wanted to add to what you've written above. The article summary along with the title are the only things that the user has to judge whether an article will answer their question or not. I refer to this as "User Confidence" and it directly impacts click thru. Even if we serve the correct article at the top of the search results list, the user needs to make the mental connection between the search query and the results we display for them to click thru. For articles that are more troubleshooting in nature, we should put the symptoms in the summary as that is likely what the user will search. Verdi gave a great example of a troubleshooting article above. If an article is more of a general information type article we should use the summary field to list the topics covered in the article. Here is an example search: [https://support.mozilla.org/en-US/search?e=es&product=desktop&q_tags=desktop&q=Open+window+in+new+tab Open window in new tab] Now take a look at the fourth result in the list. Here is what you'll see:<br> '''Article Name:''' Options Window - Tabs Panel<br> '''Summary:''' This document explains all of the preferences available in the Tabs panel of the Preferences window of Mozilla Firefox. For other panels, see Preferences window. As an end user, I've got no way of connecting the search that I've entered with the information displayed for this article so I won't click on it. It would be far more enticing if it looked something like this:<br> '''Article Name:''' Tab Options and Behavior<br> '''Summary:''' The Options Window - Tabs Panel allows you to customize tab behaviors such as opening new windows in tabs, warnings for opening/closing multiple tabs, displaying the tab bar at all times, and switching to new tabs immediately. You can really see how little information we are giving in search results if you do a search for [https://support.mozilla.org/en-US/search?e=es&q=options options]. It's probably not a very common search, but this illustrates the point as most of the summaries simply repeat the title of the document. One last thing to mention is that we should always give search higher priority than browse navigation when we are naming our documents and writing summaries. Why you ask? Because we can manually change the title of a document to fit our task based navigation and we won't be showing the summary! We don't have the luxury to change the titles in search results. This is something that can be done with best bets and tailored searches, but that is a conversation for a different thread!
  3. Reply with summary suggestions for the articles below.

    P.S. You can use Twitter as a character counter. Just don't exceed -20 characters to keep your summary to the 160 recommended characters.

    <blockquote> Reply with summary suggestions for the articles below. *[[Firefox makes unrequested connections]] *[[Firewalls]] *[[JavaScript]] </blockquote> *[[Firefox makes unrequested connections]] **This article explains the different connections to the Internet that Firefox makes and how you can control them. *[[Firewalls]] **A firewall controls what other programs on your computer can connect to the Internet. This article explains how to make sure Firefox is allowed to connect. *[[JavaScript]] **JavaScript is used by websites to add interactive features like menus, sounds and more. This article explains how to control what JavaScript is allowed to do. P.S. You can use Twitter as a character counter. Just don't exceed -20 characters to keep your summary to the 160 recommended characters.
  4. Looks good verdi ;) Here are some that I put together. This is really going to improve findability!


    Looks good verdi ;) Here are some that I put together. This is really going to improve findability! * [[Firefox makes unrequested connections]] ** Firefox periodically checks for things like anti-phishing updates, extension block lists, and auto-updates. This article explains each connection and shows you how to manage them. * [[Firewalls]] ** A Firewall is the gatekeeper between programs on your computer and the internet. This article will show you how to be sure that Firefox is allowed access.
  5. I've never really been happy with using the phrase "This article explains...". Wasn't there data from the UX team that users are not familiar with the term "knowledge base article"? Or it may have just been "knowledge base". Is there a more familiar word we should use, like 'document' or 'page'? Or maybe stay away from starting summaries with "This ... explains..."

    I've never really been happy with using the phrase "''This article explains...''". Wasn't there data from the UX team that users are not familiar with the term "knowledge base article"? Or it may have just been "knowledge base". Is there a more familiar word we should use, like 'document' or 'page'? Or maybe stay away from starting summaries with "This ... explains..."
  6. That's a solid point Chris. In a previous KB I worked on we realized one day that every article summary started out with "This article..." From a search results standpoint it's too uniform to catch the eye and just becomes extra noise. I don't think it would be a bad idea to try not to use the phrase if possible. If it is used, we definitely need to vary the usage.

    What do you think Verdi?

    That's a solid point Chris. In a previous KB I worked on we realized one day that every article summary started out with "This article..." From a search results standpoint it's too uniform to catch the eye and just becomes extra noise. I don't think it would be a bad idea to try not to use the phrase if possible. If it is used, we definitely need to vary the usage. What do you think Verdi?
  7. Good point. I don't think "article" is bad. Wikipedia, newspapers and magazines all use it. I agree that prefacing that with "knowledge base" is not good idea and "document" sounds too technical to me. But I think we can vary the phrase and placement or skip it where it makes sense. Some examples:

    • This article explains...
    • We'll show you...
    • We'll explain...
    • This page explains...
    • This article describes...
    • We'll spell out how to...
    Good point. I don't think "article" is bad. Wikipedia, newspapers and magazines all use it. I agree that prefacing that with "knowledge base" is not good idea and "document" sounds too technical to me. But I think we can vary the phrase and placement or skip it where it makes sense. Some examples: * This article explains... * We'll show you... * We'll explain... * This page explains... * This article describes... * We'll spell out how to...
  8. So to try to bring this to a conclusion, I'm proposing the following as the guide to writing a summary:

    How to write an article summary

    The article summary along with the title are the only things that the user has to judge whether or not an article will answer their question. We call this "User Confidence" and it directly impacts click through rates. Even if we serve the correct article at the top of the search results list, the user needs to make the mental connection between the search query and the results we display in order for them to click through to the article.

    A summary for a how-to article should include the topics covered in the article. A troubleshooting article should try to include symptoms. In addition, a summary should follow these guidelines:

    • Short and to the point. Remember classified ads? Write it like that. Search engines cut off anything longer than 160 characters.
    • Don't use wiki markup.
    • Don't use "This article explains" in every summary. Vary it when possible. Some other phrases to consider:
      • We'll show you
      • We'll explain
      • This page explains
      • This article describes
      • We'll spell out
    So to try to bring this to a conclusion, I'm proposing the following as the guide to writing a summary: ==How to write an article summary== The article summary along with the title are the only things that the user has to judge whether or not an article will answer their question. We call this "User Confidence" and it directly impacts click through rates. Even if we serve the correct article at the top of the search results list, the user needs to make the mental connection between the search query and the results we display in order for them to click through to the article. A summary for a how-to article should include the topics covered in the article. A troubleshooting article should try to include symptoms. In addition, a summary should follow these guidelines: * Short and to the point. Remember classified ads? Write it like that. Search engines cut off anything longer than 160 characters. * Don't use wiki markup. * Don't use "This article explains" in every summary. Vary it when possible. Some other phrases to consider: ** We'll show you ** We'll explain ** This page explains ** This article describes ** We'll spell out
  9. Looks great Verdi! This was a great exercise!

    Looks great Verdi! This was a great exercise!