- Created by Robert Reiner, last modified on 14. Nov 2018
projectdoc Toolbox
FAQs help to record an answer to a frequently asked question concerning the project, the product, the system or the process.
- ID
faq- Suite
- Documentation Type
- Categories
- Tags
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.
But make sure that the FAQ is short and focussed. There is very little structure in this list and the simple question/answer format may be too easy to pour any information in. Instead documentation should be structured and goal orientated.
Read The problem with Frequently Asked Questions (FAQs) in documentation by Tom Johnson for more information on FAQs and how they should be used properly.
Properties
The document type provides only standard properties.
Sections
Description
The description provides an overview over the question, usually defining the context. This makes the question shorter and allows it to be scanned quicker.
For simple questions, where the context is clear, the description is often overkill. Sometimes even the Short Description is more than is needed. But for complex environments, it may come handy. Check if the context may be transcluded from a Module document.
Question
Formulate the question from the reader's view, in the context defined in the Description. Try to make it short and precise. Readers scanning the questions should find it easy to locate the relevant documents.
Try to put the reader in the question. Refer to the reader with "I". This helps to take the right direction for formulating the question and makes it easier for readers to identify themselves with the questioner.
- How can I ...?
- What is the intended configuration for me to ...?
- Where can I find ...?
But not all questions follow this pattern as in
- What is ...?
- What does ... stand for?
Answer
Make the answer short and precise. Maybe add links for readers to find more information on this topic quickly.
Since questions and answers are usually aggregated on pages to form lists, it may make sense to add links to this section in addition to links in the References and Resources sections.
Subordinate FAQs
A list of FAQs that are closely related to this FAQ and therefore are attached as children to this document.
Notes
These are internal notes that are usually not exported and only visible to team members with write access.
But this is not a safe place to store sensible information. It is just a convenience for the reader to not be bothered with notes stored here for the authors for later use. The security level is about suppressing the representation by a CSS style. Therefore consider this as a convenience for the reader, not as a security tool.
The text of notes sections is also indexed.
References
For a document the references section contains pointers to resources that prove the statements of the document.
Often these proofs are not easily distinguishable from further information. In this case you may want to skip the reference section in favour for the resource list.
For further information please refer to References and Resources.
Resources
The resources section provides references to further information to the topic of the document.
This may be information on the internet provided by the resource or information in the team's information systems. Anything the reader of the resource might want to know, may be listed here.
For further information please refer to References and Resources.
Details
Categories 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.
Hierarchies
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.
Name 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.
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 ..."
Index 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.
One 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:
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.
