Difference between revisions of "Site Guidelines"

From GMOD
Jump to: navigation, search
m (Destination Filenames)
m (Destination Filenames)
Line 105: Line 105:
 
The '''Destination filename''' is the name the file will have in the GMOD web site.  Why does this matter?  Filenames are displayed in [[Categories]], but none of the text in the file is.  Therefore the filename should describe the contents of the file.
 
The '''Destination filename''' is the name the file will have in the GMOD web site.  Why does this matter?  Filenames are displayed in [[Categories]], but none of the text in the file is.  Therefore the filename should describe the contents of the file.
  
For example, the file [[Media:Gkl777.pdf|Gkl777.pdf]] is an article on [[ParameciumDB]] from ''Nucleic Acids Research'', but if you look at the file's listing in the [[:Category:Publications]|Publications category]] all you see is "Gkl777.pdf".  You have to follow the link to find out what the file is about.
+
For example, the file [[Media:Gkl777.pdf|Gkl777.pdf]] is an article on [[ParameciumDB]] from ''Nucleic Acids Research'', but if you look at the file's listing in the [[:Category:Publications|Publications category]] all you see is "Gkl777.pdf".  You have to follow the link to find out what the file is about.
  
 
=== File Categories ===
 
=== File Categories ===

Revision as of 19:27, 17 April 2008

This page discusses editorial policies and best practices to follow when updating or creating content in the GMOD web site.

Introduction

The GMOD web site editorial policies and best practices are defined here. Consistent use of these policies and practices will hopefully lead to a 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 followed by the actual guidelines, describing how content should be created.

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 if the guidelines discourage people from contributing in the first place, then they have defeated the whole purpose.

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

However, once you get comfortable with MediaWiki, 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 the GMOD Help Desk. Alternatively, you can post them to this page (or to this page's discussion/talk page).

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 you write won't be deleted, but it might be modified to follow the guidelines if and when somebody notices.

Guidelines

This is a list of guidelines for creating content in the GMOD web site. Some guidelines are accompanied by discussion that explains them.

Guidelines are shown like this.

Discussion is shown as regular text.

Page Names

Capitalization

Use Generous Capitalization instead of Parsimonious capitalization.

For example, use "Site Guidelines" instead of "Site guidelines".

It looks better.

Redirects

Use of MediaWiki redirects for page name synonyms is encouraged.

This means that if a user types "editing guidelines" in the "Go/Search" box and you have a redirect defined for "Editing Guidelines" then they will go directly to this page, instead of the search results page.

A slight downside of this is that the Special:Allpages view now displays lots of pages that are only redirects to other pages. This turns into more of an index than a listing of all pages.

Minor Edits

If you want the page you are editing to be listed in the New & Revised Pages list on the GMOD home page, then do not mark your edit as a minor one.

When you update a page in this web site you can flag it as a minor edit. As of December 2007, the minor/major edit distinction is used in one place in the GMOD web site: Major edits (that is, edits that are not marked as minor) cause the page to be listed in the New & Revised Pages list on the GMOD home page. That list is a reverse chronological ordering of all recent non-minor edits

If your edit is small, such as a spelling or other typo correction, then mark it as a minor edit.

Tags / Categories

Tag any pages you edit with appropriate categories for that page.

Be generous in your tagging. If a particular category gets too many pages in it then the help desk will subdivide that category.

This web site makes extensive use of tags, called categories in MediaWiki, to flag pages as being related to different topics. To encourage the use of categories, an input field and tag cloud listing existing categories is shown at the bottom of every edit page. You can either type in the category name or click on the category in the tag cloud to add it to the current page.

As of January, 2008 we are still adding category tags to pages. Once that work is closer to complete, categories will be prominently featured in site navigation.

New Categories

If you think we need a new category then create it.

You can create a new category by typing the new category name in the Categories form on an edit page.

When creating a new category please:

  • Check that the new category is not redundant with an existing category.
  • Create a category only if it will apply to more than one page.
  • Add the category to other pages that it applies to.
  • Create the category page for the new category.
    • Include a description of the category in the page.
    • Also, make the new category a subcategory of any existing categories it could be a subcategory of.
      • You do this by using, you guessed it, the Categories form on the edit page when creating the category page.

Or, just send your new category suggestion to the GMOD Help Desk and we will add it.

Uploading Files

Destination Filenames

When uploading a file, please give the file a meaningful Destination filename.

The Destination filename is the name the file will have in the GMOD web site. Why does this matter? Filenames are displayed in Categories, but none of the text in the file is. Therefore the filename should describe the contents of the file.

For example, the file Gkl777.pdf is an article on ParameciumDB from Nucleic Acids Research, but if you look at the file's listing in the Publications category all you see is "Gkl777.pdf". You have to follow the link to find out what the file is about.

File Categories

When uploading a presentation or a paper, please add it to the Presentations or Publications categories. Also add the file to any other appropriate categories.

If the file is an image that is being linked to from a page then you don't need to categorize it.

Diagrams and Cartoons

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

This will allow others (and yourself) to modify the diagrams in the future rather than recreate them from scratch.