Writing good FAQs: Difference between revisions

Revision as of 18:13, 12 November 2011

Aim to name FAQs, such that they can easily found in an index

Prefix the FAQ with the main scope, e.g. Xen, XCP, XenARM, etc.
Then add FAQ
It is good to group FAQs related to a topic, e.g. Linux, Installation, etc.
If the topic is too large qualify, e.g. Linux, Running on, Linux, Building for Xen, etc.

Good FAQs typically have the following attributes:

The question is clearly and concisely covered at the beginning of the FAQ
They use simple and clear language
They avoid the excessive use of technical language or add a definition of a new term
They tend to be self containing, i.e. they limit the number of external links
They contain examples, scripts, etc.

@@ Line 1: / Line 1: @@
+== Conventions: Naming FAQs ==
+Aim to name FAQs, such that they can easily found in an index
+* Prefix the FAQ with the main scope, e.g. '''Xen''', '''XCP''', '''XenARM''', etc.
+* Then add '''FAQ'''
+* It is good to group FAQs related to a topic, e.g. '''Linux''', '''Installation''', etc.
+* If the topic is too large qualify, e.g. '''Linux, Running on''', '''Linux, Building for Xen''', etc.
+== Attributes ==
 Good FAQs typically have the following attributes:
-* The question is clearly and concisely covered at the beginning of the FAQ (a shorter version should be in the title)
+* The question is clearly and concisely covered at the beginning of the FAQ
 * They use simple and clear language
 * They avoid the excessive use of technical language or add a definition of a new term