Difference between revisions of "Writing good FAQs"

From Xen
(Migrated from FAQ category)
 
(Added FAQ Naming Conventions)
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:
 
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 use simple and clear language
 
* They avoid the excessive use of technical language or add a definition of a new term
 
* They avoid the excessive use of technical language or add a definition of a new term

Revision as of 18:13, 12 November 2011

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
  • 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.