cancel
Showing results for 
Search instead for 
Did you mean: 

Anatomy of a Knowledge Base article

These instructions apply to a new tool we are transitioning to in a few weeks.

You want to learn how to write help articles for Mozilla Support? This is the right place to start. We'll give you a crash course of our tools, techniques and style. Bookmark this page and use it as a guide as you get started writing articles. You'll learn it by heart in no time.

In general, we have two basic types of articles with two kinds of introductions:

  • Tutorial or "how-to" article intros: A brief summary of the feature or task and what things can be learned (example).
  • Troubleshooting article intros: A brief summary of the symptoms and the solution (example).

The editing tool has two editing modes: rich text and HTML. With rich text, you can write without any markup. Just use the formatting tools above the window to add lists, images or structure your content for certain platforms.

How to structure an article

Think of an article like you would a story, because readers have an easier time understanding and building skills if told in a logical order. There is a beginning, middle and end. In this context, the beginning would tell users a little bit about the feature or issue being discussed. What is it and why should they care? The middle would give them step-by-step explanations of how to use or resolve the subject. The end would give readers the option to deepend their knowledge by learning more advanced steps.

For example, in this Tab Groups article we start with why you should use the feature, then move on to how to make a group and finish with more complicated tasks like searching and organizing.

Write descriptive section headings so readers can scan through quickly

Naming the section header after the task or the solution allows the reader to quickly browse the article or scan the table of contents to see the scope of the article. In some cases this may already provide enough information for some users and they wouldn't even need to read the rest of the article.

Create step-by-step instructions

There's nothing more frustrating than to finally find the instructions you need and then get stranded while trying to follow them because the writer assumed you knew something you didn't. This is why we break our instructions down into complete, numbered steps. If you have to click "OK" at some point we even define that as a step.

Here's an example from the How to set the home page article:

  1. Open a tab with the web page you want to use as your home page.
  2. Drag and drop that tab onto the Home button Home Button .
    Home Page 29 - WinXP Home Page 29 - Win8 Home Page 29 - Mac Home Page 29 - Linux
  3. Click Yes to set this page as your home page.

Create instructions for different operating systems or versions of Firefox

Often Firefox instructions are different for the different operating systems. We have special wiki markup that shows Windows instructions to Windows users and Mac instructions to Mac users. If you switch the operating system at the top of this article, the appropriate steps below will change according to the selected operating system.

  1. Click the menu button New Fx Menu and choose Options.
  2. Select the General panel.
  3. In the Startup box under Home Page: click Restore to Default.
    HomePage-Fx34Win
  4. Click OK to close the Options window.

  1. Click the menu button New Fx Menu and choose Preferences.
  2. Select the General panel.
  3. In the Startup box under Home Page: click Restore to Default.
    HomePage-Fx34Mac
  4. Close the Preferences window.

  1. Click the menu button New Fx Menu and choose Preferences.
  2. Select the General panel.
  3. In the Startup box under Home Page: click Restore to Default.
    HomePage-Fx34Lin
  4. Click Close to close the Preferences window.

Use templates in your step-by-step instructions

There are a lot of common steps in Firefox articles. For these we create "templates" so that we don't have to write (and translate) them over and over again. Usually templates include instructions for all operating systems which simplifies and accelerates the writing of the single steps a lot. Here are the same steps as shown above but this time written by using templates.

  1. Click the menu button New Fx Menu and choose Options.Preferences.
  2. Select the General panel.
  3. In the Startup box under Home Page: click Restore to Default.
    HomePage-Fx34Win HomePage-Fx34Mac HomePage-Fx34Lin
  4. Close the about:preferences page. Any changes you've made will automatically be saved.

Customize this article

Firefox

Version History
Revision #:
3 of 3
Last update:
3 weeks ago
Updated by:
 
Tags (1)
Comments

Can't see step 4 ( the [[T:closeOptionsPreferences]]) in "Use templates in your step-by-step instructions" area, and the screenshot also, it is only me ? ? ?

thank you

It's not just you. I think when I moved this article into the "Contributor Resources" category, it broke the {for} code. I moved it back to "Firefox" so it should work in a few minutes.

Thanks for reporting this and I apologize for my mistake. :)

Joni

I can't select anything with "Customize this article". It's just empty.

Oddly enough i see instructions/screenshot both linux and mac but not windows. And im using windows.

"should work in a few minutes". "August 12, 2014". It didn't work then.

Does the article have to be under the Firefox product for the "Customize this article" to work ?

Because I properly asked for it to be removed from there, because its not about the Firefox browser.

The article it is still in "Contributor" category not in "Firefox" category, to be honest the article must be in "Contributor" category, as it is.

Why is the "Customize this article" not working in this article ?

The issue affects other articles besides this one. The discussion is now taking place in this thread:

The content of the general panel have changed so it have have the "Make Firefox my defalut browser" button.

So instead of "Home page Win3" image, maybe we should use another image that looks the same in different versions and then change the steps to match the image, what ever image if selected as the new one.

Differences : https://support.mozilla.org/en-US/gallery/image/20441 https://support.mozilla.org/en-US/gallery/image/6047

These Windows and Mac screenshots have been added to the How to set the home page article for fx34: (I don't have one for Linux):

https://support.mozilla.org/en-US/gallery/image/20441 HomePage-Fx34Win

https://support.mozilla.org/en-US/gallery/image/20454 HomePage-Fx34Mac

I tried making an edit to add the above screenshots but it doesn't display correctly. {for} isn't working, even after adding Firefox to the Description "Relevent to" section. You can try yourself in an hour or so. Hopefully the Description change will take effect soon.

I just added Firefox to the Description "Relevant to" section. It's now relevant to both Firefox and Contributors. "Customize this article" for Firefox should display soon.

The Description change that added "Relevant to:" Firefox has taken effect and {for} is working now. I updated the article to include the fx34 and other changes in the example How to set the home page article.

I also updated instructions for opening options/preferences with the menu button, which changed in fx29.

My revision is pending review. Have I missed anything?

I added a Linux screenshot and other small edits to my last revision, based on updates that were just made to the How to set the home page article.

I think the part about:

under Home Page:

Is more confusing then helpful.

Should we remove it ?

I think it's fine.

Laucon

I looked at Artist's edits and I believe that they help tremendously. Thank you so much.

A new contributor has just made a revision to the current, approved version of this article (I'll defer that revision).

There are unreviewed edits to this article going back to February 8, 2016. The last edit by Joni on Mar 7, 2016, had the comment, in progress, do not review. What's the status?

AliceWyman said

A new contributor has just made a revision to the current, approved version of this article (I'll defer that revision). There are unreviewed edits to this article going back to February 8, 2016. The last edit by Joni on Mar 7, 2016, had the comment, in progress, do not review. What's the status?

See this Google doc. Looks like Joni is still working on this article. The Google doc comment is "Part of this needs to be rewritten for Lithium".

I edited the Description Relevant to: section and removed Firefox, so that Contributors was the only product selected. I also edited Topics to remove the Firefox entry and added a Contributors topic.