View source for TechWiki:Guidelines

These '''guidelines''' will create consistency for additions and corrections to the TechWiki.

== Creating new articles ==
An '''article''' in this wiki should be similar to an encyclopedia article. It should cover a single topic, and should stand on its own (although it may and generally should link to other articles). Topics may be very broad, or quite specific.

=== Appropriate content ===
All pages (including uploaded files) should fit within the scope of the wiki: [[Clerks|clerk-related topics]], [[Family Safety]], [[Tech|Tech projects]], and [[Meetinghouse Technology]]. This wiki is '''not''' a place for individuals or units of the Church to upload files or other information that is for the use of only individuals or specific units. No private information (names, phone numbers, email addresses, membership details, etc.) may be posted. And of course, all content should be consistent with Church standards, policies, and doctrine. 

=== Article title ===
The '''title''' of the article should be chosen carefully. It should describe the content well, and be a term that others would naturally apply to this content. A user of the wiki can type a title in the '''search box''' of the wiki and click '''Go''' (or press '''Enter''') and go directly to an article if an article with that title exists. Words in titles should not be capitalized, except for the first word and any proper nouns.

Product titles should generally be capitalized as in [[Meetinghouse Technology]] and not "Meetinghouse technology".

If the article title needs to provide context, include the context in parentheses after the title. For example, "Rights and roles (directory)" is distinguished from "Rights and roles (calendar)"; using this convention puts the significant words of the article upfront where they are more visible (as opposed to "Calendar rights and roles"). 

Do '''not''' use a slash to create subpages to provide context (e.g., "Calendar/Rights and roles") since this wiki reserves the use of subpages in the main namespace for the [[TechWiki:Translation|translation]] procedure; subpages also have the unfortunate effect of obscuring the significant words of a title later in the title where they are not as visible.

Except for [[TechWiki:Translation|translated]] titles, do not use the '''<nowiki>{{DISPLAYTITLE}}</nowiki>''' magic word to change the title, except for capitalization (e.g., a title that starts with a lowercase letter such as "iPhone") and other minor changes. Significantly changing the title using DISPLAYTITLE breaks the convention that the displayed title should match the page name and thus the page link (see the [https://www.mediawiki.org/wiki/Manual:$wgAllowDisplayTitle#Details MediaWiki documentation]).

=== Before creating a page ===
Before you create a new page, make sure that
* The content is not already covered on another page
* The content is appropriate to the Tech Wiki
* You have chosen an appropriate title

=== Introduction ===
Every wiki article should begin with a brief introduction. This allows readers to know at a glance the subject matter of the article. Where it is reasonable, the title of the article (or the significant words from the title) should appear early in the article (preferably at the very beginning) and should be '''bolded'''. Look at the introduction to this article for an example.

The introduction should not have any heading (such as "Overview" or "Summary"); since an introduction has no heading, it will appear at the very top of the article, before the table of contents, which makes it appropriately prominent.

=== Point of view ===
All articles should be written in third person. There may be situations, particularly for [[:Category:Projects|projects]], where an individual may report an experience or take responsibility for an action item. In such situations, do not use first person, and never sign your name (as you would with a discussion page). Instead, use a link to your username (e.g., <code><nowiki>[[User:Aebrown|Aebrown]]</nowiki></code>) and refer to yourself in the third person (e.g., "[[User:Aebrown|Aebrown]] will report back on the decision of the executive team").

== Editing pages ==
The content of the wiki makes progress because many users make contributions, from making simple spelling corrections to adding new articles. Be bold so that you move the project forward, but don't be hasty -- sloppy edits will just create more work for others and lower the quality of the wiki.

=== Use the Visual Editor ===
The [[VisualEditor]] handles most of the formatting available in the wiki. It allows you to copy and paste from other formatted text sources and maintain much of the formatting. You can switch back and forth between Visual Editing and source editing.

=== Use Preview ===
In source editing, before you click '''Save page''' to save your changes, use the '''Show preview''' button to see how your changes will actually appear. This can help save you from posting content with obvious errors.

=== Make changes at one time ===
Use the preview button liberally as you are creating a page or making edits. Whenever possible, make all your changes to a page in a single session. If you save the page often, you will needlessly clutter the history of the page and fill up the '''recent changes''' log with many entries. This makes it more difficult for other users to discover what has actually changed.

=== Headings ===
The [http://meta.wikimedia.org/wiki/Help:Section#Creation_and_numbering_of_sections MediaWiki style guide] suggests avoiding H1 level headings (i.e., <code>= This is an incorrect article heading =</code>) in your articles, as those type of headings are used for the article titles.  All article sub-headings should begin with H2 level headings (i.e., <code>== This is a correct article heading ==</code>) and then go downwards from there. Words in headings should not be capitalized, except for the first word and product names or other proper nouns. Headings should not include wikilinks or any wikitext (see Wikipedia article on [http://en.wikipedia.org/wiki/Wikipedia:ACCESS#Links links]).

=== Links ===
Links (both wikilinks and external links) should be attached to text that is a natural part of the article. Avoid the common blog practice of putting links around the word "here."
* '''Incorrect''': Read the MediaWiki Handbook [http://meta.wikimedia.org/wiki/Help:Contents here].
* '''Correct''': Read the [http://meta.wikimedia.org/wiki/Help:Contents MediaWiki Handbook].

=== Minor edits ===
As  you save your changes after editing a page, there is a check box labeled "This is a minor edit." As explained in the [http://en.wikipedia.org/wiki/How_to_edit#Minor_edits Wikipedia article on minor edits], these are to be used only for "typo corrections, formatting and presentational changes, rearranging of text without modifying content, etc. A minor edit is a version that the editor believes requires no review and could never be the subject of a dispute." Any addition of new content can never be a minor edit, even if it is not a lot of text.

=== Categories ===
Every article should be in at least one category. Generally you add a category by adding something like '''<nowiki>[[Category:Android applications]]</nowiki>'''. As with article titles and headings, categories should not use title case. In general, when a subcategory is included, the parent category is not explicitly included (e.g., since [[:Category:Community Services SSO]] is a subcategory of [[:Category:Community Services]], an article in the ''Community Services SSO'' category would not be explicitly included in the ''Community Services'' category).

Before you create a new category, check to see if a similar category exists (see the [[Special:Categories|list of all categories]]), and follow existing naming conventions where possible.

=== Style guide ===
For consistent formatting and usage of common words and concepts, please reference the [[TechWiki:Manual of Style|style guide]].

=== Changing the title ===
If you need to change the title of an article, do not simply create a new article and copy the content from the old page to the new page. Instead, use the MediaWiki '''[http://en.wikipedia.org/wiki/Wikipedia:How_to_rename_(move)_a_page Move]''' feature (one of the top tabs). '''Move''' lets you specify a new title for the page, then moves the content and the associated talk page to the new page, and finally edits the old page to be a redirect to the new page. This is far easier than doing it manually. It also keeps the discussion page with the new title, which is generally desirable, and leaves a clearer history of the actual title change.

== Discussion pages ==
Each article has a '''discussion page''' or '''talk page'''. These pages provide a forum for the community to come to a consensus as to the direction a particular article should take. If there is anything at all controversial about a change you have made or think ought to be made, start a discussion using the discussion pages.

You should '''never''' put discussion, questions, or comments in the body of articles. Discussion should be limited to the discussion page.

=== Topics ===
Discussion pages can be organized into topics. This is particularly helpful for articles that have multiple sections and thus may have ongoing discussion related to different sections.

If you are responding to a particular question, use one or more colons to indent your response so that it is clear what comment or question you are responding to.

=== Sign your name ===
You can easily sign your name by adding four tildes to the end of your comment. This will add your username and a time stamp. You can use three tildes for just your name or five tildes for just the timestamp, but the preferred signature uses four tildes to include both. The appearance of your username is determined by the preferences you have set. Comments in discussion pages should always be signed, but signatures should not be placed in articles.

== Add sources ==
Although opinions and personal ideas can be helpful, statements purported to be official Church policy will be more effective if backed up from [[official sources]]. You may want to use the [http://www.mediawiki.org/wiki/Extension:Cite/Cite.php#Usage Cite extension] to document the reference to the source.

== Formatting code ==
The wiki provides options for formatting inline code or blocks of code. For inline code elements, use the '''<nowiki><tt></nowiki>''' or '''<nowiki><code></nowiki>''' tag; for multi-line blocks of code, use the '''<nowiki><pre></nowiki>''' tag or the Syntax Highlighting extension.

=== Inline code elements ===
For formatting inline code, such as references to variables, methods, filenames, or other code elements, use the '''<nowiki><tt></nowiki>''' or '''<nowiki><code></nowiki>''' tag. Each of these will produce text in a monospaced font. 

{| border=1
! WikiText !! Result 
|-
|<pre>... implement the <code>ISerializable</code> interface ...</pre>
|... implement the <code>ISerializable</code> interface ...
|-
|<pre>... modify the <tt>pom.xml</tt> file ...</pre>
|... modify the <tt>pom.xml</tt> file ...
|-
|}
{{-}}

=== Syntax Highlighting ===
We have Syntax Highlighting on the wiki so that if you paste source code snippets, they will show up with highlights. The [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi MediaWiki SyntaxHighlight extension documentation] explains how to use syntax highlighting for your source code (including Java, HTML, SQL, XML, and many more). Here's a simple example:

{| border=1
! WikiText !! Result 
|-
|<pre><syntaxhighlight lang="java">
    public static void main(final String[] args)
    {
        // Here is a comment
        System.out.println("Hello, World!");
        int m = 3 * 4;
    }
</syntaxhighlight>
</pre>
|<syntaxhighlight lang="java">
    public static void main(final String[] args)
    {
        // Here is a comment
        System.out.println("Hello, World!");
        int m = 3 * 4;
    }
</syntaxhighlight>
|-
|}
{{-}}

== Translation ==
{{main|TechWiki:Translation}}
To translate pages into languages other than English, follow the documented [[TechWiki:Translation|translation]] procedure, which will insure consistent linking between different language versions of articles.

==Outdated content==
If a project is no longer active and the information no longer needed, the project page should be removed from the wiki. Deleting a page requires administrative or employee permissions, so please add a note on the page indicating that it is no longer needed. You can also contact a [[Special:ListUsers/sysop|wiki administrator]].

== Use templates to flag questionable or incomplete content ==
If you come across an article that needs to be edited or should be deleted, you can flag the article by inserting a template. To do this, simply edit the article and insert the text '''<nowiki>{{Template_Name|Parameter}}</nowiki>'''. The parameters for a template are documented on the template page, which you can examine by going to the appropriate template page: '''<nowiki>Template:Template_Name</nowiki>'''.

=== Template:Edit ===
Use the {{tl|Edit}} template if you find a page that requires editing, but you don't have the time or skill to edit it. This template may be inserted at the top of the page if it applies to the entire page, or at the beginning of a section if it only applies to that section. It has a parameter that is a brief description of what needs to be corrected. For example, the annotation
<pre>{{Edit|Eliminate first person from this section}}</pre>
would result in a box appearing in the text as follows:
{{Edit|Eliminate first person from this section|category=}}

=== Template:Rename ===
Use the {{tl|Rename}} template if you find a page that should be renamed, but you don't have the time or skill to do it. This template may be inserted at the top of the page if it applies to the entire page, or at the beginning of a section if it only applies to that section. It has a parameter that is a brief description of why it should be renamed. For example, the annotation
<pre>{{Rename|Title should reflect the product}}</pre>
would result in a box appearing in the text as follows:
{{Rename|Title should reflect the product|category=}}

=== Template:Delete ===
Use the {{tl|Delete}} template to flag a page for deletion. For example, the annotation
<pre>{{Delete|This page is spam}}</pre>
would result in a box appearing in the text as follows:
{{Delete|This page is spam|category=}}

=== Template:Draft ===
Use the {{tl|Draft}} template for policy or guideline pages that are in a draft stage (do not confuse this with {{tl|stub}} which is used for incomplete pages or {{tl|Under construction}}). This template should be inserted at the top of the page. It has a parameter that is a brief description of the reason for the draft status. For example, the annotation
<pre>{{Draft|Waiting for approval}}</pre>
would result in a box appearing in the text as follows:
{{Draft|Waiting for approval|category=}}

=== Template:Need Input ===
Use the {{tl|Need Input}} template when a particular issue in an article or discussion requires additional information, clarification, or collaboration.  Indicate what is needed with a brief description of the issue or ask a question.  For example, the annotation
<pre>{{Need Input|Should Bishops be able to assign responsibility for a household to a quorum?}}</pre>
would result in a box appearing in the text as follows:
{{Need Input|Should Bishops be able to assign responsibility for a household to a quorum?|category=}}

=== Template:Unresolved ===
Use the {{tl|Unresolved}} template for marking a question or concern as currently unresolved in discussions on Talk Pages.  This template should be inserted at the top of an unresolved discussion.  It has a parameter that is a brief description of the issue.  For example, the annotation
<pre>{{Unresolved|This database architecture is too complicated}}</pre>
would result in a box appearing in the text as follows:
{{Unresolved|This database architecture is too complicated|category=}}

=== Template:Resolved ===
Use the {{tl|Resolved}} template for marking a question or concern as resolved in discussions on Talk Pages.  This template should be inserted at the top of a resolved discussion.  It has a parameter that is a brief summary of the resolution and resultant action.  For example, the annotation
<pre>{{Resolved|Added to the Use Cases}}</pre>
would result in a box appearing in the text as follows:
{{Resolved|Added to the Use Cases|category=}}

=== Template:Stub ===
Use the {{tl|Stub}} template to indicate that an article is only a stub and needs to be fleshed out. This template takes no parameter, and appears as:
{{stub|category=}}

=== Template:ToDo ===
Use the {{tl|ToDo}} template to indicate tasks that need to be performed on an article.  It has a parameter that is a brief summary of the tasks requiring action.  For example, the annotation
<pre>{{ToDo|Create a detailed instructions page to show how to configure this application}}</pre>
would result in a box appearing in the text as follows:
{{ToDo|Create a detailed instructions page to show how to configure this application|category=}}

=== Template:Merge ===
Use the {{tl|Merge}} template to indicate that two or more pages contain duplicate content and should be merged into one.  It has a parameter that you should use to include links to each of the pages in question.  For example, the annotation
<pre>{{Merge|Merge this page with the [[Main Page]]}}</pre>
would result in a box appearing in the text as follows:
{{Merge|Merge this page with the [[Main Page]]|category=}}

=== Template:Split ===
Use the {{tl|Split}} template to indicate that the current page is too long, and needs to be split into multiple pages. For example, the annotation
<pre>{{Split}}</pre>
would result in a box appearing in the text as follows:
{{Split|category=}}

=== Template:Under construction ===
Use the {{tl|Under construction}} template to indicate that a page is under construction, so users should avoid significant edits. It has an optional parameter that specifies a message to be included. For example, the annotation
<pre>{{Under construction|This page will be completely overhauled on 21 Aug 2010}}</pre>
would result in a box appearing in the text as follows:
{{Under construction|This page will be completely overhauled on 21 Aug 2010|category=}}

==Additional information==
For more information on working with [http://www.mediawiki.org MediaWiki], see the [http://www.mediawiki.org/wiki/Help:Formatting formatting guidelines] from MediaWiki's help site.

[[Category:Help]]
[[Category:Administration]]