Help:Maintaining Help

Under Construction

Help pages as described here are under construction, beginning Dec 2016. Note that the Help:FAQ page link (below) is to a pre-existing help page that has not yet been changed according to this plan.

Organization of WeRelate Help Menu

WeRelate Help is organized according to actions a user may wish to carry out (as opposed to, for example, being organized according to WeRelate's menu structure). Help topics are grouped into major headings, and presented more-or-less in the order we would expect a new user to use functions.

Considerable thought was put into organizing WeRelate Help. This means that changes to the organization should not be made lightly. However, it is expected that WeRelate Help, including its organization, will evolve (particularly while it is still under initial development).

Structure of WeRelate Help

Before you attempt to modify WeRelate help pages, you need to be aware of the structure, which was designed to:

• reduce redundancy (making it easier to maintain)
• reduce inconsistency
• allow tighter control over conventions such as date formats

WeRelate conventions

WeRelate conventions are documented in a set of subpages under the page Help:Conventions. These subpages are the only place conventions should be documented. That is, other Help pages should not attempt to document any of these conventions, but instead should include or link to these pages.

Convention pages

Each convention topic has the following pages:

• Help:Conventions/topic
  • This page includes headings.
  • The first heading is "Quick reference", following by: <div class="wr-infobox wr-infobox-help">{{Conventions/topic/Quick reference}}</div>
    
  • The remainder of the page presents additional details, including (as appropriate) exceptions and rationale (titled "Why enter data this way?").
• Template:Conventions/topic/Quick reference
  • This page doesn't include any headings (because they can mess up the TOC of pages where transcluded).
  • This page presents a short (1-3 paragraph) description of the main points we want all users to be aware of.
  • If more than one paragraph is included, enclose paragraphs in <p></p>. Otherwise, paragraph spacing might not be consistent when the page is transcluded.
  • The last thing on this page is: <noinclude>[[Category:Help Templates]]</noinclude>, to make it easier to find all Help text stored in the Template namespace in the future. (noinclude tags are important so that pages where it is transcluded are not also added to the category.)
  • Note: This page is not intended to be accessed directly by users - its purpose is to be transcluded on other pages that are on the Help menu. Because it is in the Template namespace, it doesn't show up when searching in the Help namespace.
• Template:Conventions/topic/Link
  • The only content of this page is: <p>For more information, see [[Help:Conventions/topic|topic conventions]].</p>
  • The paragraph markup (<p></p>) is required to ensure that the link is in a new paragraph when transcluded.

Some conventions topics have subtopics (e.g., the various name fields in the person name convention). Each convention subtopic has a page:

• Template:Conventions/subtopic
  • This page is constructed exactly the same as a "Template:Conventions/topic/Quick reference" page.

When modifying the headings on a topic page, make sure any links from a subtopic page still go to the right place.

Referencing a convention

Any Help page that refers to a convention includes:
<div class="wr-infobox wr-infobox-help">{{Conventions/topic/Quick reference}}{{Conventions/topic/Link}}</div>

For an example, see Help:Creating a Person page, which includes the Quick Reference from and links to Help:Conventions/Date.

When transcluding a convention subtopic page, the "div" tag can be left off. For example, the "div" tag is not used for the Template:Conventions/Type of name on the Help:Conventions/Person name page.

The main Help:Conventions page transcludes the Quick Reference of all conventions subpages. There is a direct link from the Help menu to the Help:Conventions page, allowing the user to easily find all conventions in one place.

"How To" instructions

There are a number of "how to" instructions that are useful in more than one situation, such as "how to change a page title". Each of these instructions is written on a subpage of Help:HowTo.

The structure and usage of these pages is the same as for convention pages.

The collection of HowTo subpages is presented as Frequently Asked Questions on the Help:FAQ/HowTo page (through transclusion). The parent Help:HowTo page (which is not used in the Help Menu structure, but might be looked at when maintaining a subpage), simply replicates the Help:FAQ/HowTo page by transcluding it.

Frequently asked questions

Frequently asked questions are grouped by Help topic, with each group having its own subpage of Help:FAQ. Where applicable, a Help page transcludes the relevant FAQ subpage. The page Help:FAQ also transcludes all subpages, so that users can see all FAQs in one place and can search them all at once.

Headings on a FAQ subpage should be formatted like this: ====What is the question?====

Instructions vs. tutorials

By default, WeRelate Help is instructions on how to use WeRelate functionality and isn't considered to be tutorials (since tutorials typically include exact data for the user to enter and show the results of entering that data).

Tutorials may be created, but should be in addition to (not instead of) the instruction pages. Since tutorials provide exact data to enter, they have to be executed in the sandbox). They also need to accommodate for the fact that someone else may have completed the tutorial since the last time the sandbox was refreshed.

Tutorials typically do not need to describe conventions, since they provide all the data to enter, but if they do, they need to transclude and/or link to conventions pages, just like other Help pages do.

Protecting Help pages

Help pages (including Template pages that are part of Help, as documented above) should be protected so that only Administrators can change them. Talk pages should be open to discussion by the WeRelate community. Both Help pages and corresponding Talk pages should be monitored.