Locked History Actions

Wiki Best Practices

Wiki Best Practices

The Galaxy Wiki editorial policies and best practices are defined here. Consistent use of these policies and practices will hopefully lead to a more consistent and readable web site.

This page first introduces meta-guidelines. These are guidelines about these guidelines and cover things like how to update the guidelines, and when you can ignore them. These are far more important than the actual guidelines that follow them.

See also Wiki Help.

Meta-Guidelines

Or, Guidelines on Guidelines.

Ignoring

Q: Can I ignore these guidelines?

A: Yes.

We would much rather have a contribution that completely ignores these guidelines than not have the contribution at all.

This is for pragmatic and philosophical reasons. The whole goal of a wiki is to encourage people to contribute and maintain content. Site guidelines encourage a clean and well organized web site, but guidelines that discourage contributions have defeated the whole purpose.

It also takes some time to become proficient at MoinMoin (the wiki package behind this web site), and it can be a challenge to learn MoinMoin details and site policies at the same time.

However, once you get comfortable with MoinMoin, please think about writing your content so it does conform to these standards.

Updating

These guidelines are a work in progress and you are encouraged to suggest additions, deletions or revisions to them. The best way to do this is to send your comments to Galaxy Outreach.

Enforcing

Q: Is there any enforcement of these guidelines?

A: Not really.

Beyond the usual wiki practices, there is no enforcement of these guidelines. This means that any non-conforming material won't be deleted, but it might be modified to follow the guidelines if and when somebody notices (and cares).

Guidelines

Did you read the Meta-Guidelines yet? They are more important.

This is a list of guidelines for creating content in this wiki.

  1. Best practices are shown like this.

Discussion is shown as regular text.

Page Names

  1. Use Generous Capitalization instead of Parsimonious capitalization.

  2. Use CamelCase page names.

  3. Use of MoinMoin redirects for page name synonyms, and CamelCase equivalents is encouraged.

CamelCase page nemaes are strongly preferred as Separate Word page titles lead to awkward URLs with lots of embedded %20's (URL-escaped spaces). You get

instead of the much prettier

MoinMoin vs Creole Syntax

  1. You can use either, but not on the same page.

Galaxy's previous wiki used Creole. All of MoinMoin's pages use MoinMoin's markup. Use whatever you are most comfortable with.

Tags / Categories

We are still working out details in this area.

Uploading Files

  1. If a uploaded file is likely to be useful on more than one page, please upload it to the Images or Documents wiki page hierarchies.

  2. Please give the file a meaningful name when uploading it.
  3. When uploading a diagram or cartoon that was created in a drawing program upload the exported image file (png, jpg, gif) and the original image source file as well. Load both files with the same name, but different extensions.

Formatting

Formatting is the boogieman of many sets of best practices. Only worry about this section if you really care.

Type of Text

Minimum formatting
and how to achieve it

Better formatting
and how to achieve it

Files, directories, paths

Raw

Open config/galaxy.ini

Open {{{config/galaxy.ini }}}

Shown

Open config/galaxy.ini

Open config/galaxy.ini

GUI
Interaction

Raw

Go to Upload Tool under Get Data,
and enter the multiple URLs
into the URL / Text box. 

''Navigate'' to 
'''Get Data → Upload Tool'''
and ''enter'' the multiple URLs
into the '''URL / Text''' box. 

Shown

Go to Upload Tool under Get Data, and enter the multiple URLs into the URL / Text box.

Navigate to Get Data → Upload Tool and enter the multiple URLs into the URL / Text box.

Shell
output

Raw

{{{
~/galaxy-dist$ sqlite3 database/universe.sqlite
SQLite version 3.6.16
Enter ".help" for instructions
Enter SQL statements terminated with a ";"
sqlite>
}}}

Shown

~/galaxy-dist$ sqlite3 database/universe.sqlite
SQLite version 3.6.16
Enter ".help" for instructions
Enter SQL statements terminated with a ";"
sqlite> 

Code

Raw

{{{
<tool id="get_flanks1" 
      name="Get flanks">
  <description>
    returns flanking region/s for genes
  </description>
  <command interpreter="python">
    get_flanks.py $input ...
  </command>
...
}}}

{{{#!highlight xml
<tool id="get_flanks1" 
      name="Get flanks">
  <description>
    returns flanking region/s for genes
  </description>
  <command interpreter="python">
    get_flanks.py $input ...
  </command>
...
}}}

Shown

<tool id="get_flanks1" 
      name="Get flanks">
  <description>
    returns flanking region/s for genes
  </description>
  <command interpreter="python">
    get_flanks.py $input ...
  </command>
... 

   1 <tool id="get_flanks1" 
   2       name="Get flanks">
   3   <description>
   4     returns flanking region/s for genes
   5   </description>
   6   <command interpreter="python">
   7     get_flanks.py $input ...
   8   </command>
   9 ...