User:N8wilson/new FAQ

This page is still in development and very likely to change. Questions or comments can be directed to User_talk:N8wilson. Until the content has been moved out of userspace, please do not use this content on other pages.

Todo list

[edit]

test a non-numeric link-key
take template code out of wikitext using magic somehow ([1])?
make empty q and a but valid link-key show the pre-gen message about not changing the link-key

Documentation[view] [edit] [history] [purge]

This template should always be substituted (i.e., use {{subst:User:N8wilson/new FAQ}}).

Create a new {{FAQ item}} on a /FAQ subpage.

This is a convenience template that helps correctly auto-fill the link-key parameter when creating {{FAQ item}}s on /FAQ pages as well as automatically surround newly created {{FAQ item}}s with properly coded <section> tags to make the link-key function as intended. {{subst:new FAQ}} can also be used to convert older {{FAQ row}} templates in a single step.

This template has no visible effect when transcluded or safesubst:'ed.

Usage

[edit]

This template is designed to be used in several different ways:

1. Generate a skeleton for adding a new FAQ question

{{subst:new FAQ}}

This is a convenience use case. Saving this wikitext will cause it to replace itself with a more complete list of all parameters in the template.

2. Migrate an older-style {{FAQ row}} template to the newer {{FAQ item}} format

{{FAQ row
|index=...
|q=...
|a=...
}}

can simply be replaced with

{{subst:new FAQ
|index=...
|q=...
|a=...
}}

This will replace itself with a call to {{FAQ item}} and the old index will be preserved. If the index is a number, it will also be converted to a link-key in the new FAQ system so the question can be referenced individually.

This method can also be used to correctly update an existing {{FAQ item}} when adding a link-key to a question that does not already have one assigned. Replacing {{FAQ item}} with {{subst:new FAQ}} will add appropriate <section> tags around the item which are required for link-keys to work as intended.

3. Manual use

{{subst:new FAQ
|index=
|q=
|a=
|short-a=
|discussions=
|wp-editor-notes= <!-- ... -->
|link-key=
}}

Fill in parameters manually. The link-key parameter has special restrictions. It may be left empty if you're not familiar with those requirements. See each parameter's description below for more details. If link-key is correctly completed, this template will create a {{FAQ item}} and will also generate a copy of itself ready for substitution in "placeholder" mode (which is described next) with the an incremented link-key value already pre-filled.

4. Placeholder

{{subst:new FAQ
|q=
|a=
|short-a=
|discussions=
|wp-editor-notes= <!-- ... -->
|link-key=...
}}

If either of the q and a parameters are left empty, substituting this template will have no effect. Technically it will still substitute however the substitution results in another copy of the same substitution call to itself with all the same parameter values still set. This allows it to sit at the end of a FAQ page for future editors as a hint on how to fill in the next question that needs to be added. Once it's completed, as indicated in "Manual use" above, a new {{FAQ item}} is created and the placeholder is re-generated with a new link-key value.

Parameters

[edit]

index: A carryover from {{FAQ row}} that may be displayed as the question number (i.e. index=5 → "Q5"). If this is provided as a numeric value, it may be used to create a link-key for the resulting {{FAQ item}} if the link-key parameter is not also set (link-key takes priority). Index does not have to be a number though. A value of "3.a." is perfectly fine. In such cases however, this template cannot automatically generate a suitable link-key as well.

q: Same usage as {{FAQ item}} - the question text

a: Same usage as {{FAQ item}} - the full answer text

short-a: Same usage as {{FAQ item}} - a short answer for use by some templates

discussions: Same usage as {{FAQ item}} - a list of links to relevant previous discussions contributing to the answer

wp-editor-notes: This is a dummy parameter that can be left blank or set to anything without any effect whatsoever on the resulting {{FAQ item}} that gets created. It exists so this template can leave a helpful message to editors who might not initially see the result the expect when using this template. Values the template fills in here will always be wrapped in an HTML comment.

link-key: Stable and unique number that can be used to link directly to the created FAQ item. The same number must not be re-used for multiple FAQ items on the same FAQ page. If this is the first FAQ on a page, any number can be used. If there are existing FAQs already present, use 1 + the highest link-key already in use. When using {{new FAQ}} with the link-key provided, the template will pre-generate a stub call to the next {{new FAQ}} item with the next available link-key pre-filled in this parameter. Usually if you find this parameter already completed – even if nothing else is filled in – the value should not need to be changed. To be clear that this is not the same number as the index – which may sometimes be displayed as the question number – it is considered good practice to set link-key to a 3 or 4 digit unique code. If link-key is provided, it will override any number in the index parameter.

New FAQ Plan

[edit]

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:

Make FAQs visible in mobile views for reading. (FAQ editing on mobile is neither included nor excluded as a possibility.)
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

The above documentation is transcluded from User:N8wilson/new FAQ/doc. (edit | history)
Editors can experiment in this template's sandbox (create | mirror) and testcases (edit) pages.
Add categories to the /doc subpage. Subpages of this page.