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 {{FAQ item}} 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 {{pin FAQ}} and referenced individually using {{see FAQ|x}}. The {{new FAQ}} 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 {{see FAQ}}.

discussions

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

format={{{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 {{{format|}}}. Rather than creating a {{FAQ item}} manually and forgetting to set this, consider substituting {{new FAQ}} 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 index 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 link-key value for the {{FAQ item}}.

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 <noinclude> tags around the item and outside the corresponding <section> 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).

Case Breakdown: How N8wilson/FAQ item/doc is rendered

Any non-talk namespace

format = <not-checked; output format is overridden> 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

format = <empty> 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

format = <empty> 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

format = "pinned" (passed by {{pin FAQ}}) Pinning the FAQ using the {{pin FAQ}} template treats the entire /FAQ page as a template and passes the value "pinned" to every instance of {{FAQ item}} 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

New FAQ Plan

This template is part of a new system of templates for handling frequently asked questions (FAQs) on talk pages. The goals of this new system are:

1. Make FAQs visible in mobile views for reading. (FAQ editing on mobile is neither included nor excluded as a possibility.)
2. Allow editors to include the text of a single question+answer within an active discussion for reference.

These are the planned system of templates:

• {{FAQ item}} - Structured record of consensus on a frequently asked question or frequently discussed topic.
• {{subst:new FAQ}} - Create a new {{FAQ item}}. Also used as a drop-in replacement to convert older {{FAQ row}}s.
• {{pin FAQ}} - Placed at the top of a talk-space page to pin the FAQ to the top of the discussion area.
• {{see FAQ|x}} - Includes text of a specific question and answer in a discussion.

---

Templates: subst:new FAQ     FAQ item     pin FAQ     see FAQ
Example: User:N8wilson/FAQ on talk page: User talk:N8wilson