Help:Maintaining Help

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.

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">{{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?").
• Help:Conventions/topic/Quick reference
  • This page doesn't include any headings (because they can mess up the TOC of pages where this page is 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 isn't consistent when the page is transcluded.
  • The last thing on this page is: <noinclude>{{Help:Conventions/topic/Link}}</noinclude>
  • 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. However, it will show up in search, and users might access it directly, which is why the link is included. The link is inside <noinclude></noinclude> so that it doesn't show up on the Help:Conventions/topic page.
• Help: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.)

Each conventions subpage has the following sections:

• Quick reference - this presents a concise statement of conventions, surrounded by <onlyinclude> and </onlyinclude> tags. The usage of these tags means that the subpage can be included in another page and only the Quick Reference section will be displayed. Note: In order for inclusions to display with appropriate paragraph breaks, include the following between paragraphs instead of a blank line: <br><span style="line-height:0.5"><br></span>

The last statement in this section (before the ending </onlyinclude> tag) should be "<includeonly><br><span style="line-height:0.5"><br></span>For further information, see [[Help:Conventions/subpage|subpage conventions]].</includeonly>" The <includeonly> tag means that this statement (and link) will be displayed only when the subpage is included on another page.

• Further information - this section presents all the detail that is required about the conventions.

Any Help page that needs to refer to conventions includes {{Help:Conventions/subpage}}, which can be indented as follows:

<p style="margin-left: 25px">{{Help:Conventions/subpage}}</p>

For an example, see Help:Conventions/Dates, which is included in Help:Creating a Person page.

When modifying the Quick reference section of a Conventions page:

• Check to ensure that it is still correctly enclosed by <onlyinclude> and </onlyinclude> tags
• Check to ensure that "For further information see <link>." doesn't display in the subpage itself.
• Check all pages that include the conventions page (What links here) to ensure that the inclusion still reads appropriately in context, and includes "For further information see <link>."

The main Help:Conventions page includes 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.

Conventions subpages are monitored by the Overview Committee and watched by anyone with an interest in them. This helps to ensure that conventions are not changed without appropriate community discussion (on their respective talk pages). The Overview Committee reserves the right to reverse any change to conventions that has not first been appropriately discussed on the talk page. The Overview Committee also reserves the right to protect any conventions subpage from editing by anyone other than an Administrator.

"How To" instructions

There are a handful of "how to" instructions that are useful in more than one situation, such as "how to rename a page". Each of these instructions is written on a subpage of Help:HowTo. The contents and usage of these pages is the same as for the conventions pages.

When modifying the Quick reference section of a HowTo page:

• Check to ensure that it is still correctly enclosed by <onlyinclude> and </onlyinclude> tags
• Check to ensure that "For further information see <link>." doesn't display in the subpage itself.
• Check all pages that include the HowTo page (What links here) to ensure that the inclusion still reads appropriately in context, and includes "For further information see <link>."

The collection of HowTo subpages is presented as Frequently Asked Questions on the Help:FAQ/HowTo page (through inclusion). 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 including 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 includes the relevant FAQ subpage. The page Help:FAQ also includes all subpages, so that users can see all FAQs in one place and can search them all at once.

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 include and/or link to conventions pages, just like other Help pages do.