Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Document Properties Marker
overridefalse
Short DescriptionFAQs help to record an answer to a frequently asked question concerning the project, the product, the system or the process. 
Doctypedoctypehide
NameFAQ 
IDfaq 
SetCore 
Parent
Parent Property
property-nameName
 
Audience
Name List
doctyperole
render-no-hits-as-blanktrue
propertyAudience
 
Documentation Type
Name List
doctypedoctype-type
render-no-hits-as-blanktrue
namesQ1 - Process, Q2 - Project, Q3 - Product, Q4 - System
propertyDocumentation Type
 
Categories
Name List
doctypecategory
render-no-hits-as-blanktrue
namesDocumentation
propertyDocumentation Type
 
Tags
Tag List
namesCore, Project
 
Iteration
Iteration
valuefocused
hide
Sort Keyhide
Section
indextrue
titleDescription

The main purpose of a question and answer document is to make it easy for readers to find answers to their question. It is easier to match one's question in an index, than to run a number of searches on a pile of documents. So in essence a FAQ is a tool for readers to get an answer quickly.

...

Section
titleDetails
Section
level2
titleCategories are important

Make sure to categorize your question and answer by using Tags and Categories. But the most important tool for categorization is the intended Audience. If your FAQ grows in numbers, a natural structuring information is the intended audience. So you may want to get it right from the start.

The Categories property has to match the semantics of other document types, too. This is seldom an issue, but if you need more fine-grained categories, you may alter your template and add some additional properties. The same is true for Tags.

Section
level2
titleHierarchies

Constructing hierarchies of FAQ documents usually only makes sense, if the parent FAQ defines a question that is the context for some more questions. Keep in mind that the child FAQs also have to be understood independent from their parent. So check if this structure really supports finding information quickly with feedback from your readers.

Section
level2
titleName and Short Description

The question and the answer are the most important sections of this doctype. The name and especially the short description properties are often difficult to formulate. The information may be not relevant, since everything is already said in the Q and A. The time invested for finding appropriate information for these properties may not be justified by the additional help given.

So if you intend to never list the name and short description, you may enter some arbitrary ids and you are done. But since a description may set the context of the question, a short description may be valuable to readers.

Names make is also easier, if your want to reference an FAQ from another document.

So you my use a phrases for the Name of an FAQ and a Short Description to set the context of the question in one to three sentences.

Example Box

For instance the question is "Why do I encounter so Ys since we decided X?".

The name of the FAQ document my be "Y is not a consequence of X".

The short description may read. "Since we decided to use X, which significantly enhanced our product for A, we seem to encounter more problems in respect to Y. But actually this is not true. Analysis has show that Y relates to X."

And the answer might start like this: "While it seems that the decision of X led us to a problem with Ys, the root cause of this problem is the new X. The reason ... You find more information about X in ..."

Section
level2
titleIndex Documents

Keep in mind that document instances of the FAQ doctype are usually compiled into lists that only show the question and the answer. So expect readers to not read the description and especially the References and Resources section.

The Space Index for the central FAQ documents usually get divided into a link collection to pages that compile questions for a given audience or category.

If you think it is important to show the context specified as Short Description and/or Description, make sure that everyone on the team knows and appreciates the benefits, since this is an all-or-nothing: It does not make sense to specify the context for some of your FAQ, if you list either of the information in overview lists. So check if you may just stick to the question and answers sections. Usually it is best to start with descriptions as optional and design your queries to list only questions and answers.

Section
level2
titleOne Document for one Question/Answer Pair

Authors may be used to compile questions and answers directly in a definition list on one page. But having one document for each pair has the following advantages:

Definition List

Compilation into different Lists

One FAQ document may be interesting for different audiences or categories. If you compile the FAQ by transclusion or referencing, this helps to not duplicate information.

Read Restriction

You may opt to restrict access to a particular FAQ so it does not show up in the lists. This may be useful if the FAQ is still not finished or the document is only for internal use.

Referenceability

A document is usually easier to reference than an element in page. Especially browsers are known to not jump exactly to the element, especially if the element is at the end of a page and the browser's viewport is large.

Section
indextrue
titleRelated Doctypes

...

Section
titleReferences

Section
titleResources

Piwik Set Multiple Custom Variables
NameValue
Departmentprojectdoc
Categoryprojectdoc-doctype
Typecore