====== Style guide ======

Please use the following **style guide** when creating and maintaining article pages on this wiki.

===== Introduction to DokuWiki syntax =====
As an introduction, Andreas Gohr has a couple of short DokuWiki video tutorials at 
[[http://www.splitbrain.org/blog/2008-10/05-dokuwiki_beginners_screencast_01|DokuWiki Beginners Screencast #1 and #2]].   --- //[[jlong@soe.ucsc.edu|Jeff Long]] Tue Mar 30 13:45:05 PDT 2010//

Refer to the [[wiki:syntax|formatting syntax]] guide for any questions regarding formatting syntax.


===== Where to try things out =====

If you want to test your changes before editing a wiki page you can do so at the [[playground:playground]].

===== Editing an article =====
  * First navigate to the editor page using the pencil icon at the side of the page. 
  * Make your edits in the text box. 
  * For small changes like spelling errors or fixing capitalization choose 'minor changes'.
  * For more significant changes provide a brief summary. 
  * Click the preview button to see your changes, review them to ensure they are as you expect. 
  * Click the save button to update the wiki. 

===== How to format articles =====

==== When to create a new article ====
When considering adding new content to the wiki, you may be tempted to create a new article. Before creating a new article page, please review the following criteria:
  * Does a page already exist that would be suitable for the new content? Use the search function at the top of the page or view all of the pages available on the wiki using the "Index" button at the bottom of the page to check.
  * Will the new content have enough material (now or at some point in the future when more content will be added) to warrant the creation of a new article?

==== Creating a new article ====

In order to add a new article, follow these steps:
  - Navigate to an article that already exists that you would like to link to your new article.
  - Add the internal link to your new page in that article by surrounding the desired page name with braces.
Ex. [[playground:playground]]
  - Follow the link to your new article and click on the "Create new page" button.

==== Adding a file ====

In order to add an file (.pdf etc), follow these steps:
  - Edit the page where the file should be linked.
  - Click the 'Add images and other files' button (fourth icon from the right). 
  - A new window will open displaying the media files.
  - Upload the file to the media files. 
  - Select the uploaded file. 

==== Article formatting ====

=== Title ===
When creating an article title, please keep the following guidelines in mind:
  * Only capitalize the first letter in the title as you would in a normal sentence. Exceptions include, but are not limited to, capitalizing proper nouns and capitalizing names.
  * Please try to keep the article title short in length, preferably no more than 10 words in length.
  * Avoid the use of any special characters, unless the characters are a part of a proper noun or name.
Please use headline level 1 formatting when creating the article title, as illustrated in the syntax below:

<code>
====== Article title ======
</code>

=== Sectioning ===
When creating a new section for an article, use the following guidelines:
  * As with the article title, only capitalize the first letter of the section heading. Exceptions include, but are not limited to, capitalizing proper nouns and capitalizing names.
  * Keeping section headings unique within any given article is strongly preferred.
  * A blank line before the section heading is required for the sake of readability when editing.
Sample headline levels for use in section headings are given below:

<code>
===== Headline level 2 =====
==== Headline level 3 ====
=== Headline level 4 ===
== Headline level 5 ==
</code>

=== Table of contents ===
When three or more headlines are used on a given page, a table of contents is automatically generated. Headline levels 3 or greater are not included in the table of contents.

===== Citations =====

==== When to use citations ====
Use the following guidelines to know when to cite your sources on the wiki:
  * If you are using a direct quote, be sure to cite it. Try to avoid the use of direct quotations if possible.
  * If you are paraphrasing, be sure to cite it.
  * If the material is not original research, then it should be cited.

==== How to create citations ====
Citations and references sections can be done with the installed [[http://www.dokuwiki.org/plugin:refnotes|RefNotes plugin]]. Refer to the [[http://www.dokuwiki.org/plugin:refnotes:syntax|RefNotes syntax]] guide for any questions regarding the RefNotes syntax.

=== Using the RefNotes plugin for citations ===
The syntax for creating a named reference note is:

<code>
[(cite:refname>This is a reference)]
</code>

The //namespace// (e.g. cite) for the note is located before the ":" symbol. The namespace organizes notes by assigning the note to a specific group of notes, which in this case is used to group the notes by citations.

The //name// (e.g. refname) for the note is located between the ">" symbol and the ":" symbol and must be an alphanumeric string that starts with a letter. The name can be used to refer to this citation again without having to create a new citation. In order to cite the same note repeatedly, you can use the following syntax:

<code>
I have a sample sentence I want to cite.[(cite:refname>This is a reference)]
Here is a sentence using the previous citation by automatically numbered note.[(cite:#1)]
Here is another sentence using the previous citation by named note.[(cite:refname)]
</code>

All notes added are automatically linked and numbered by the plugin. It is possible to create unnamed citations without the ">"; however, this may cause issues later when citations have changed and the automatic numbering has changed as well, so it is //always better to create named notes//. Named notes also can be used before they are defined later in the text, as illustrated below:

<code>
Here is a sentence using a yet to be defined citation by named note.[(cite:refname)]
...
I have a sample sentence I want to cite.[(cite:refname>This is a reference)]
</code>

=== Using the RefNotes plugin for references sections ===
The RefNotes plugin can be used to automatically create a references section for any given article using the note syntax. In order to create the references section, the syntax is:

<code>
~~REFNOTES namespace~~
</code>

In the case for this wiki, you would use:

<code>
===== References =====
<refnotes>notes-separator: none</refnotes>
~~REFNOTES cite~~
</code>

to create the references section for any given article using the notes syntax with "cite" as the namespace for the citations.

===== Formatting =====

==== Gene symbols ====
When referring to a gene symbol (not the gene name), please use italics. Refer to the example syntax below:

<code>
The sonic hedgehog gene, //Shh//, is a part of the hedgehog signaling pathway and plays a role in vertibrate organogenesis.
</code>

==== Genera and all lower taxa ====
When referring to genera and all lower taxa (e.g. genus species), please use italics. Refer to the example syntax below:

<code>
In BME 235, we will be working with the //Ariolimax dolichophallus// genome.
</code>

==== Protocols ====
When listing any form of protocol, please use a numbered list. A numbered list is created by indenting the text by two spaces and using a dash for the list element. Refer to the syntax below:

<code>
An ordered/numbered list:
  - List element 1
  - List element 2
  - etc.
</code>

==== Wikipedia links ====
When creating links to Wikipedia, use the interwiki hyperlink type. Use the following syntax to create an interwiki link:

<code>
For Wikipedia:
[[wp>Main_Page]]
</code>

Refer to the [[doku>Interwiki]] page for a list of different websites that you can use with Interwiki links.