Difference between revisions of "HowTo and FAQ Style Guide"

Revision as of 15:42, 28 May 2010

This style guide is intended to provide wiki contributors with a template and style suggestions to use when writing HowTo articles and Frequently Asked Questions (FAQs).

Writing FAQ Entries

Frequently Asked Questions (FAQs) are intended to reduce the workload and traffic in the forums by putting the replies to common questions in a single location where they can be easily found. The format for a FAQ should follow a question / answer pattern. The questions should be similar to what is asked in the forums and stated explicitly as a question. The answer needs to be short with links to further reading if required.

The wording in the question should reflect the level of knowledge of the intended user and avoid terminology they may not understand at the time they ask the question. The question should also reflect a specific task the user is trying to perform. For example:

• Bad: How do I use the application dictionary?
• Better: How do I add a column to a table?
• Better yet: How do I add a new field to a window form?

When writing the FAQ, keep the intended user in mind. Basic questions from first time users can be treated differently than complex questions from developers. In the organization of the FAQs, place the question/answer in the appropriate hierarchy.

There is a template for FAQs here Template:FAQ

To use it, enter your question and answer pair as follows:

{{FAQ|question=How do I use the FAQ Template?|answer=Just like this. Note that the variable names are case sensitive. The template use heading level five for the question so it will appear in a table of contents.}}

The result will appear in the page as follows:

Q: How do I use the FAQ Template?

Just like this. Note that the variable names are case sensitive. The template uses heading level five for the question so it will appear in a table of contents.

Writing HowTo Guides

HowTo articles explain in detail the process to acomplishing a task. To be effective, the HowTo should be written with a tarket audience in mind and should provide the reader with something to learn.

Note: This section will be developed soon!