User Tools

Site Tools


about_the_class:style_guide

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 DokuWiki Beginners Screencast #1 and #2. — Jeff Long Tue Mar 30 13:45:05 PDT 2010

Refer to the 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.

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:

  1. Navigate to an article that already exists that you would like to link to your new article.
  2. Add the internal link to your new page in that article by surrounding the desired page name with braces.

Ex. playground

  1. 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:

  1. Edit the page where the file should be linked.
  2. Click the 'Add images and other files' button (fourth icon from the right).
  3. A new window will open displaying the media files.
  4. Upload the file to the media files.
  5. 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:

====== Article title ======

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:

===== Headline level 2 =====
==== Headline level 3 ====
=== Headline level 4 ===
== Headline level 5 ==

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 RefNotes plugin. Refer to the 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:

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

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:

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)]

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:

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)]

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:

~~REFNOTES namespace~~

In the case for this wiki, you would use:

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

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:

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

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:

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

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:

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

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

For Wikipedia:
[[wp>Main_Page]]

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

Discussion

, 2010/04/02 16:48

refnotes has been installed. Check it out and see how well it works. Chris, you might want to provide a short “how to cite” section and a pointer to the refnotes documentation.

, 2010/04/03 01:15

The RefNotes plugin seems to work well. However, when I try to set the extra line that is generated in the references section used to separate note blocks from the rest of the article

<refnotes>notes-separator: none</refnotes>

I get PHP warnings. Could you look into changing the level of PHP warnings displayed in use on the server where the wiki is installed, or possibly change the “Notes block separator” option on the admin page for the RefNotes plugin (if it indeed an option there for it) to “None”?

, 2010/04/03 12:31

I enabled php inclusion for the wiki, and I changed the refnotes reference formatting to use brackets instead of superscripts.

, 2010/04/03 18:18

It seems that the PHP warnings appear in the preview before submitting an edit, but disappear after the edit is saved, so the problem is no longer an issue.

, 2010/04/02 15:06

In Progress

We need to decide on and implement an official format for citations; using footnotes is “totally lame”. Any suggestions? — 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? — Kevin Karplus 2010/03/30 15:40

refnotes seems the most promising option. There's also cite, but its description is very vague. Too bad the bibtex one has a reported and unpatched major vulnerabilty. — Jenny Draper 2010/03/30 16:04

It looks like the refnotes plugin should be sufficient for assisting in formatting the citations needed for the wiki. The 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.

Also, I have found the 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? — Christopher Brumbaugh 2010/04/02 08:04

You could leave a comment if you were logged in.
about_the_class/style_guide.txt · Last modified: 2015/07/27 22:54 by ceisenhart