User:N8wilson/FAQ item/doc

A structured record of local consensus regarding a frequently asked question (FAQ) or frequently discussed topic on a specific talk page.

Use on the /FAQ subpage in a talk namespace to store a record of a frequently asked question. Items recorded with this template can be "pinned" to the top of a talk page using and referenced individually using. The template may be helpful in quickly and correctly completing this template with a more limited set of parameters.

Parameters

 * index
 * Displayed question number or label. This is aesthetic only and is not used in creating references to questions. For that purpose, see "link-key" below. Unlike "link-key", this parameter may be changed after it has been initially assigned if, for instance, the questions are re-ordered or re-grouped.


 * q
 * question text


 * a
 * answer reached by consensus


 * short-a
 * Shorter answer used by some templates when displaying information about this topic. The short answer may for instance be preferred in the mobile interface or when an editor references a specific question using.


 * discussions
 * List of links to previous discussions that contribute to the consensus described in this FAQ item


 * format=
 * Pass-through parameter that can be set whenever this FAQ item is transcluded into another page. This is a required parameter that must always be set to the value . Rather than creating a  manually and forgetting to set this, consider substituting  which will correctly set this parameter automatically.


 * link-key
 * This needs to be a unique and stable value across all questions in the same FAQ. Stable means the value of this parameter should not change once it has been set for a question. Other templates may use the value of link-key to create deep links directly to the question text. If it changes, these links will be broken. It is recommended to make the link-key at least 3 digits to avoid confusion with the  parameter which is used for display and for organizing questions.

What to do when a question changes
Significant changes -such that they change the nature of the question's primary topic- should always be recorded as a new question. If a topic is divided into two sub-topics with different answers, create two new questions and deprecate the old one. When creating a new question, always use a new  value for the.

Minor changes that update the consensus but not the nature of the topic/question can be updated just by updating the content of the 'a', 'short-a', and 'discussions' parameters. Do NOT exclude the old discussions that established the original consensus even though it has changed. This is important context to retain. It is sufficient to leave a notice about the change within the 'a' text indicating the nature, reason, and time of the change in consensus as appropriate.

How to deprecate a question no longer reflective of consensus
If the old question is no longer relevant, simply put &lt;noinclude&gt; tags around the item and outside the corresponding &lt;section&gt; tags at the beginning and end. This ensures the question will not be "pinned" when pulling the entire FAQ onto the talk page. However, it still allows the question to show up on the dedicated /FAQ page. It may also be appropriate to update the 'a' and 'short-a' parameters with a notice that the question is kept for historic reasons but no longer represent current consensus along with providing a reference to the new question(s) that reflect updated perspective on the relevant topic(s).

Any non-talk namespace
Only shows an edit-preview warning. FAQ items otherwise generate no output when used outside of a talk-space page.

FAQ on /FAQ content page
This template detects whether it is included on the /FAQ page or not. When displayed on /FAQ this template:


 * Displays all fields: index, q, a, short-a, discussions, and the link-key
 * Includes anchors to each item using anchor so that direct links and references generated with link-keys will work as expected.
 * Open questions:
 * TOC? ...use headings?
 * Collapsible?
 * Grouping?

Individual item on non-/FAQ talk-namespace page
Section transclusion cannot pass parameters to the transcluded content. Therefore, when a single question is referenced, the "format" parameter will always be empty. If the template detects that it is not generating the /FAQ content page specifically, then it assumes it is generating a single question and answer for inline inclusion in a discussion.

This use case presumes a Q+A combination is used as part of a discussion so it must honor discussion styling (primarily indention levels).


 * Displays: q, short-a if available falling back to a, "read more" link generated from link-key if available
 * Hides: index, a if short-a is available, discussions, link-key

FAQ pinned on non-FAQ page
(passed by ) Pinning the FAQ using the template treats the entire /FAQ page as a template and passes the value "pinned" to every instance of  allowing each item to create a more specific layout.


 * Display: index, q, short-a if available falling back to a, "read more" link generated from link-key if available
 * Hides: a unless short-a is not available, discussions