Wikinews:Assistant

The assistants under this parent page are sets of interactive pages to aid human users in performing various tasks — from newcomers to experts, from everyday tasks to things that might come up every few years. List them here as we write them. They are also categorized at Category:Interactive assistants.

There are some important conventions for writing assistants at the bottom of this page; eventually one would hope for one or more assistants to help with building and maintaining assistants.

List of assistants

General

Add action-test (doc)
Breadboard (doc)
View intersection (doc)
Edit items-list (create doc) (under development)
Plan imagemap (doc) (under development)

Framing

Context (doc) (under development)

Direct-action

Submit (doc)

Conventions

Page-name prefixes

Use the {{SITENAME}} magic word for the namespace of dialog actions. This avoids hardwiring the name of the project into pages that might later be used, or adapted for use, on other projects. Global assistants also use that namespace; and if explicitly referring to it, the magic word should be used; but other templates usually take care of that, as described below.

All the pages of a given assistant are either subpages of one parent, the assistant root page; or are in template space with corresponding names. The assistant root page and all its subpages belong to a category for the assistant, while the templates belong to a subcategory, and the documentation pages belong to another subcategory.

There are two naming schemes for assistant root pages, global and local.

A global-assistant root page name has the form {{SITENAME}}:Assistant:<name>. Subpages are {{SITENAME}}:Assistant:<name>/...; templates are Template:Assistant:<name>/... or occasionally Template:Assistant:<name>. The assistant category is Category:Assistant:<name>.
A local-assistant root page is a subpage of a (non-assistant) page <page> in any namespace except Template or Category. The root page name has the form <page>/Assistant:<name>. Subpages are <page>/Assistant:<name>/...; templates are Template:<page>/Assistant:<name>/... or occasionally Template:<page>/Assistant:<name>. The assistant category may vary depending on wiki-specific category-naming conventions (see here); if there is no project-organization category associated with page <page>, the assistant category is Category:<page>/Assistant:<name>; if page <page> has associated project-organization category Category:<page-cat>, the assistant category is Category:<page-cat>/Assistant:<name>.

Categorization of assistant pages is orchestrated through template {{AssistantCat}}.
There are magic word templates to derive the associated assistant page name forms for the assistant that the current page belongs to: {{ASSTDOC}} gives the name of the assistant documentation main page, {{ASSTROOT}} of the assistant root page; {{ASSTCATEGORY}} of the assistant category; {{ASSTTEMPLATE}} of the base name for the assistant's templates. {{ASSTTEXT}} returns a text description of the assistant. (There are also a few others.)

Kinds of assistants

We distinguish four kinds of assistants:

Multi-page assistants. The assistant has multiple distinct directly-viewable (i.e., non-template) dialog pages.
Single-page assistants. The assistant consists primarily of a single directly-viewable dialog page, whose layout is substantially not that of a target page (contra framing assistants, below).
Direct-action assistants. The assistant is a template providing controls on the transcluding page to immediately perform simple functions.
Framing assistants. The assistant consists of a single dialog page, accessed only through the view verb, that uses {{dialog/preview}} to display a modified form of a target page to be acted on.

Any of these may have some subsidiary pages; the distinction between them is different primary emphasis.

Root page

For direct-action assistants, the root page should be a redirect to the template. Use template {{assistant/direct-action}} on the template's documentation page.
For framing assistants, the root page should be the framing page; the view verb deliberately does not support a redirected target. Use template {{assistant/framing}}. The corresponding template page usually provides a button to invoke the framing assistant on the transcluding page.
For single-page assistants, the root page should be a dialog page, as there's no reason to make things more complicated with a redirect. Use {{dialog/ifsupported}} for graceful behavior when accessed directly as a wiki page, and {{assistant/single-page}}.
For multi-page assistants, the root page should be a redirect to a subpage, so all the major dialog pages in the assistant are on the same level. Categorize the redirecting root (via {{AssistantCat}}, as usual).

The redirect target should use {{dialog/ifsupported}} for graceful behavior when accessed directly as a wiki page, and {{assistant/viewable}}. Consider naming it {{ASSTROOT}}/start; a recognizable standard name is desirable, all the more so since any button entering the assistant via the view verb must target the subpage directly.

Primary documentation page

The primary documentation page of an assistant should always be subpage {{ASSTROOT}}/doc, except that if the assistant is direct-action, this should redirect to the template documentation.
If the root page is a redirect for a multi-page assistant, the primary documentation page should have a section for each subpage and template. These sections should be consistent with documentation of the individual pages; this can be effected via {{assistant/extract doc}}.
If the root page is instead a content page, either of two styles may be used, depending on which seems more useful to communicate the workings of the assistant:

the primary documentation page may provide a section for each subpage and template, as for a multi-page assistant (except that the section for the root page itself wouldn't use {{assistant/extract doc}}); or, alternatively,
the primary documentation page may simply provide links to other key subpages and templates in its See also section.

Other pages

Some pages of an assistant are meant to be accessed by naming them to the view verb; some pages are are meant to be transcluded onto another page; and some are made to be accessed either way. Most of the following principles are concerned with managing these different access modes, with their different behaviors.

Subpages and templates:

On a subpage, use {{assistant/viewable}}.
When transcluding a page, always pass into it all of its input parameters that are available.
When using a parameter via markup {{{...}}}, don't nest another template parameter in its default value, such as {{{foo|{{{bar}}}}}}. Non-nesting preserves substitutability by dialog parameters, since dialog parameters are (as of this writing) only substituted for non-nested template parameters.
When specifying a data field corresponding to an input parameter, specify the template parameter as an initial value, such as {{dialog/text|id=foobar|{{{foobar|}}}}}. This works for any combination of page viewed or transcluded, parameter passed by template or not, and parameter passed by dialog or not.
When specifying a button on any page, always explicitly pass out of it, as dialog parameters to the target action, all of its input parameters (except things like SUBJECT-CONTENT that aren't passed through an action request). If any of these parameters isn't stored locally as a data field (e.g., via {{dialog/text}} on the current page), explicitly specify the template parameter as a value for the outgoing dialog parameter, such as {{dialog/button/view|...|foobar::{{{foobar|}}}|...}}. This works for, again, any combination of page viewed or transcluded, parameter passed by template or not, and parameter passed by dialog or not.

Documentation pages for subpages and templates:

When documenting a subpage, use {{assistant/documentation}}.
When documenting each page of a multi-page assistant, maintain a list of the input parameters it may use, not distinguishing between template parameters and dialog parameters.
When documenting a template, use {{assistant/template}}.
When documenting a dialog edit form, use {{assistant/form}}.
To display documentation correctly when transcluded at the assistant's main documentation page, for page-relative references instead of {{OBJECTPAGENAME}} use {{OBJECTPAGENAME|{{#invoke:TScope|static}}}}.