User Tools

Site Tools


about_the_class:style_guide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
about_the_class:style_guide [2010/04/02 15:27]
cbrumbau
about_the_class:style_guide [2015/07/28 05:54] (current)
ceisenhart ↷ Page moved from style_guide to about_the_class:style_guide
Line 3: Line 3:
 Please use the following **style guide** when creating and maintaining article pages on this wiki. Please use the following **style guide** when creating and maintaining article pages on this wiki.
  
-===== Syntax reference ​===== +===== Introduction to DokuWiki syntax ​===== 
-Refer to the [[http://​www.dokuwiki.org/​syntax|DokuWiki syntax guide]] for any questions regarding formatting syntax. +As an introduction,​ Andreas Gohr has a couple of short DokuWiki video tutorials at 
- +
-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// [[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//
  
-===== Articles ​=====+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 ====
  
-==== Title ====+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: 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.   * 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.
Line 22: Line 59:
 </​code>​ </​code>​
  
-==== Sectioning ​====+=== Sectioning ===
 When creating a new section for an article, use the following guidelines: 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.   * 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.
Line 36: Line 73:
 </​code>​ </​code>​
  
-==== Table of contents ​====+=== 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. 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.
  
-===== Formatting ​=====+===== Citations ​=====
  
-==== Bold ==== +==== When to use citations ​==== 
-Use boldface ​when: +Use the following guidelines to know when to cite your sources on the wiki
-  * referring ​to the article title in the opening paragraph ​of an article+  * If you are using a direct quote, be sure to cite it. Try to avoid the use of direct quotations if possible
-  * using definition lists+  * If you are paraphrasing,​ be sure to cite it
-Boldface text is created by surrounding text with two asterisks on both sidesRefer to the following syntax:+  * If the material ​is not original research, then it should be cited.
  
-<​code>​ +==== How to create citations ==== 
-Here is some sample **boldface text**. +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.
-</code>+
  
-==== Italics ==== +=== Using the RefNotes plugin for citations ​=== 
-Use italics when referring to genera and all lower taxa, as well as gene names. Italicized text is created by surrounding text with two forward slashes on both sides. Refer to the following syntax:+The syntax for creating a named reference note is:
  
 <​code>​ <​code>​
-In BME 235, we will be working with the //Ariolimax dolichophallus//​ genome.+[(cite:​refname>​This is a reference)]
 </​code>​ </​code>​
  
-==== Underline ==== +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. 
-Underlined text is created ​by surrounding text with two underscores on both sidesRefer to the following syntax:+ 
 +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 citationIn order to cite the same note repeatedly, you can use the following syntax:
  
 <​code>​ <​code>​
-Here is some sample __underlined text__.+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>​ </​code>​
  
-==== Subscript ==== +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:
-Subscript is created ​by surrounding text with "sub" ​tags. Refer to the following syntax:+
  
 <​code>​ <​code>​
-The chemical formula for water is H<​sub>​2</​sub>​O.+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>​ </​code>​
  
-==== Superscript ==== +=== Using the RefNotes plugin for references sections ​=== 
-Superscript is created by surrounding text with "​sup"​ tagsRefer to the following ​syntax:+The RefNotes plugin can be used to automatically create a references section for any given article using the note syntaxIn order to create the references section, ​the syntax ​is:
  
 <​code>​ <​code>​
-Here is some sample <​sup>​superscript</​sup>​.+~~REFNOTES namespace~~
 </​code>​ </​code>​
  
-===== Images ===== +In the case for this wikiyou would use:
-When adding images to an articlerefer to the following guidelines:​ +
-  * Images should be located within the section with the content related to the image. +
-  * Add captions as [[wp>​Alt_attribute]] as a description to accompany an image whenever possible. +
-  * Try to avoid cramming text between two adjacent images. +
-Use the following syntax to insert images into an article:+
  
 <​code>​ <​code>​
-Internal vs. external images: +===== References ===== 
-internal +<​refnotes>​notes-separatornone</​refnotes>​ 
-{{wiki:my_image.png}} +~~REFNOTES cite~~ 
-external +</code>
-{{http://​www.dokuwiki.org/​_media/​wiki:​dokuwiki-128.png}}+
  
-Sizing images: +to create the references section for any given article using the notes syntax with "​cite"​ as the namespace for the citations.
-full size +
-{{wiki:​my_image.png}} +
-given width in pixels +
-{{wiki:​my_image.png?​50}} +
-given width and height in pixels +
-{{wiki:​my_image.png?​200x50}}+
  
-Aligning images: +===== Formatting =====
-left align +
-{{ wiki:​my_image.png}} +
-right align +
-{{wiki:​my_image.png }} +
-center align +
-{{ wiki:​my_image.png }} +
- +
-Caption: +
-alt attribute with centered image +
-{{ wiki:​my_image.png |Here is a caption as an alt text.}} +
-</​code>​+
  
-===== Tables ===== +==== Gene symbols ​==== 
-Use the following syntax ​to insert ​table into an article:+When referring ​to a gene symbol (not the gene name), please use italics. Refer to the example syntax below:
  
 <​code>​ <​code>​
-^ Heading 1      ^ Heading 2       ^ Heading 3          ^ +The sonic hedgehog gene, //Shh//, is a part of the hedgehog signaling pathway and plays a role in vertibrate organogenesis.
-| Row 1 Col 1    | Row 1 Col 2     | Row 1 Col 3        | +
-| Row 2 Col 1    | Some colspan (Note the double pipe!) || +
-| Row 3 Col 1    | Row 3 Col 2     | Row 3 Col 3        |+
 </​code>​ </​code>​
  
-The sample syntax above would create the following table: +==== Genera ​and all lower taxa ==== 
- +When referring ​to genera and all lower taxa (e.ggenus species)please ​use italics. Refer to the example ​syntax below:
-^ Heading 1      ^ Heading 2       ^ Heading 3          ^ +
-| Row 1 Col 1    | Row 1 Col 2     | Row 1 Col 3        | +
-| Row 2 Col 1    | Some colspan (Note the double pipe!) || +
-| Row 3 Col 1    | Row 3 Col 2     | Row 3 Col 3        | +
- +
-Be sure to use the same number of separators (carats or pipes) for the number of columns for each row. Whitespace between content and separators is strictly not required, but allows for easier readability. For further table formatting details, please refer to the [[http://​www.dokuwiki.org/​syntax#​tables|DokuWiki syntax guide for tables]]. +
- +
-===== Bulleted ​and numbered lists ===== +
-When deciding if it is appropriate ​to use a list, please keep the following guidelines in mind: +
-  * If the information is more easily read in paragraph format, do not use a list. +
-  * Use a numbered list only if the sequence of items in the list is necessary or you need to reference the items in the list. +
-  * If a numbered list is not required, use a bulleted list. +
- +
-==== Bulleted lists ==== +
-A bulleted list is created by indenting the text by two spaces and using an asterisk for the list element. Refer to the syntax below:+
  
 <​code>​ <​code>​
-An unordered/bulleted list: +In BME 235, we will be working with the //Ariolimax dolichophallus//​ genome.
-  * List element 1 +
-  * List element 2 +
-  * etc.+
 </​code>​ </​code>​
  
-==== Numbered lists ==== +==== Protocols ​==== 
-bulleted ​list is created by indenting the text by two spaces and using a dash for the list element. Refer to the syntax below:+When listing any form of protocol, please use a numbered list. 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>​ <​code>​
Line 159: Line 155:
 </​code>​ </​code>​
  
-===== Links ===== +==== Wikipedia links ==== 
-When creating ​hyperlinks to be added to an article, use the following guidelines:​ +When creating links to Wikipedia, use the interwiki ​hyperlink ​type. Use the following syntax to create an interwiki link:
-  * Only make links where they would be relevant ​to the context. +
-  * Double check links when you are done - make sure the link goes to where you intended. +
- +
-==== Internal links ==== +
-When adding a hyperlink to another page within the wiki, use the following syntax: +
- +
-<​code>​ +
-[[pagename]] +
-or +
-[[pagename|link text]] +
-</​code>​ +
- +
-==== External links ==== +
-When adding a hyperlink ​to a page external to the wiki, use the following syntax+
- +
-<​code>​ +
-[[http://​www.ucsc.edu]] +
-or +
-[[http://​www.ucsc.edu|University of California, Santa Cruz]] +
-</​code>​ +
- +
-==== Interwiki links ==== +
-When adding a hyperlink ​to a wiki page external to the wiki, use the following syntax:+
  
 <​code>​ <​code>​
Line 191: Line 164:
  
 Refer to the [[doku>​Interwiki]] page for a list of different websites that you can use with Interwiki links. Refer to the [[doku>​Interwiki]] page for a list of different websites that you can use with Interwiki links.
- 
-===== Citations ===== 
-Basic citations can be done with footnotes. Use a set of double parenthesis in order to create a footnote, as illustrated in the following syntax: 
-<​code>​ 
-Here is a sample sentence.((Place citation here)) 
-</​code>​ 
- 
-Footnotes are automatically numbered and linked in DokuWiki. 
- 
- --- //​[[cbrumbau@soe.ucsc.edu|Christopher Brumbaugh]] 2010/04/02 08:25// 
- 
-====== In Progress ====== 
- 
-We need to decide on and implement an official format for citations; using footnotes is "​totally lame". Any suggestions? ​ --- //​[[learithe@soe.ucsc.edu|Jenny Draper]] 2010/​03/​30//​ 
- 
-I can install various plugins for citation formatting: [[http://​www.dokuwiki.org/​plugins?​plugintag=references]]. ​ What do people think would work best? --- //​[[karplus@soe.ucsc.edu|Kevin Karplus]] 2010/03/30 15:40// 
- 
-[[http://​www.dokuwiki.org/​plugin:​refnotes|refnotes]] seems the  most promising option. There'​s also [[http://​www.dokuwiki.org/​plugin:​cite|cite]],​ but its description is very vague. Too bad the [[http://​www.dokuwiki.org/​plugin:​bibtex|bibtex]] one has a reported and unpatched major vulnerabilty. ​ --- //​[[learithe@soe.ucsc.edu|Jenny Draper]] 2010/03/30 16:04// 
- 
-It looks like the [[http://​www.dokuwiki.org/​plugin:​refnotes|refnotes plugin]] should be sufficient for assisting in formatting the citations needed for the wiki. The [[http://​www.dokuwiki.org/​plugin:​cite|cite plugin]] allows easy citation of pages on the wiki that the plugin is installed on and as such probably would not help with citation formatting. I have found the [[http://​www.dokuwiki.org/​plugin:​imagereference|imagereference plugin]] that allows MediaWiki style (e.g. Wikipedia) captions for images; this would be significantly better than just using alt text for captions. What style should we use for the citing references on the wiki? --- //​[[cbrumbau@soe.ucsc.edu|Christopher Brumbaugh]] 2010/04/02 08:04// 
about_the_class/style_guide.1270222073.txt.gz · Last modified: 2010/04/02 15:27 by cbrumbau