Main Policy

From OpenFOAMWiki
Revision as of 19:39, 31 May 2005 by Bgschaid (Talk | contribs)

This page gives an overview of the conventions in this Wiki.

1 Information submitted to this Wiki

The information in this Wiki is under the GNU Free Documentation License. This is the same license as the one used for the OpenFOAM manuals.

For more details and to learn about the consequences go to Project:Copyrights.

Please don't publish anything you don't have the rights for here. When in doubt include only a link to the material.

2 Semantic conventions

The general rule is:

  • structure the information in this Wiki in the same way it is structured in the OpenFOAM distribution
    • The sections for solvers and other applications should have subsections that mirror the directory structure of their sources
    • The annotations to the manuals are organized in a structure that mirrors the chapters of the printed versions
  • use the same nomenclature as the printed OpenFoam documentation (especially for symbols)

Reference the original source of information. One special case is if your source is a discussion from the OpenFOAM-message board: put a link to that discussion into your article.

2.1 Language

The language of this Wiki is English. If you want to write about OpenFOAM in german, latin or any other language please do so at another Wiki. If you want to I'll put a link to it on this page (or you can do so yourself - it's a Wiki).

The next question everyone is going to ask: "British or American English?". The answer: I don't care whether your language is colorful or colourful.

2.2 What goes where

The main part of this Wiki is the FAQ. Therefor this section will explain what doesn't go into the FAQ, where it goes and why.

The basic rule is: the FAQ only should have articles that

  • are of general interest (more than 3 persons have already asked that question or expressed interest in the answer)
  • can be formulated as a short, precise questions
  • can be answered in a few sentence

Therefor the exceptions are:

  • if the question is about a solver or a utility and the answer is only applicable to that application then write it in the article in Solvers or Utilities
  • if the answer is too long consider writing an article in one of the categories (and reference that article in the FAQ). Too long would mean (these numbers are only approximations):
  • if you are not aware of anybody else who is interested in that questions, write an article in Tips and Tricks. It can always be moved to the FAQ if other people express an interest in it

2.2.1 User contributed applications and examples

Applications that you want to make available to the public go into the correct section of Contributions on the Main Page.

2.2.2 Difference between Examples and Projects

If you're providing the files that are necessary to run the simulation it goes to Examples. If you're only showing pictures it goes to Projects.

2.3 Information on the pages

Some pages in this Wiki are more standardized than others. In order to make this Wiki usable certain kinds of pages should contain a minimum of standardized information.

2.3.1 Application pages

Pages about solvers and utilities should contain:

Short description 
What this application does (for the original OpenFOAM applications this would be the descriptions that are in the User Manual in the chapters 3.5 and 3.6)
Usage 
Describes the command line parameters and input files for that application. The main part of the page
Example 
Not neccessary. An example how the application was used (pictures would be nice)
Download 
Where to get the source code. Either from the Wiki itself or from an external source. Also the installation procedure if more than a simple wmake is required.
History 
Where this application originated (for instance a link to the discussion in the OpenFOAM-MessageBoard). Version history (if any)

Sign the page if you want people to contact you about that application

2.3.2 User pages

These pages should introduce OpenFOAM-users to each other (as proposed by Fabian Braennstroem in this discussion on the Message Board). This can contain anything from a link to more extensive information (but should not duplicate the information on your homepage: focus on the OpenFOAM-specific)

Information of interest is:

  • name of the institute/company (with a link)
  • your status as a user of OpenFOAM: evaluating/using/contributing/....
  • work done with Foam/OpenFoam (cross link to the Projects page if you have something there)
  • future/planed topics
  • writing code for solver, models (cross link to the contributed solvers or contributed utilities if you have something there)
  • wishes (solver, models, ...)
  • reason for using OpenFoam
  • which users of this Wiki are affiliated with your institution (and make a link back from the user pages)

Just attach your pages to the base page Users. If a sufficient number of contributions has been made I will think about a structure for this page (based on the contributions).

2.3.3 Project pages

These pages serve two purposes:

  • give people an opportunity to show the work they have done with OpenFOAM to the world
  • help to promote OpenFOAM

In the most basic version these pages provide only a link to the original pages.

In the ideal case these pages would contain:

  • name of the project
  • institution that did it (with a link to the page on Users or the homepage)
  • description
  • results
  • references to publications
  • how it was done
    • solver used
    • description of the modifications necessary (additional models etc)
    • problems

Just attach your pages to the base page Projects. If a sufficient number of contributions has been made I will think about a structure for this page (based on the contributions).

If there is enough material I'm thinking about splitting Projects into two pages:

  • Real world examples
  • Benchmark cases: Comparisons of OpenFOAM simulations with published experimental data or results of other solvers (even if their unfavorable)

2.3.4 Code snipplets

TODO

2.4 Etiquette

This section is of course not necessary, because CFD-people are widely known for their good manners and their sensitivity, but I'll write it anyway:

  • be polite
  • if an article is signed with a name then only change it after checking with the author
  • comment the quality of an article only in the attached discussion-page (an be polite)
  • when using the work of others in a signed article make it clear where you got it from
  • by signing an article you tell the others that you think that you want to edit this page exclusively (usually because it's about an application that you developed)

3 Technical conventions

To make the maintainance of this Wiki easier please conform to these conventions.

3.1 Naming things

All the uploaded pictures (and to a degree the pages) in a Wiki share the same namespace. It is therefor obvious that a picture with the name <t>temperatur.jpg</t> can only cause grief to all those who want to demonstrate some non-isothermal problem.

In other words everything that is accessed in the Wiki by it's name should have a name that

  • clearly describes it's purpose
  • makes it obvious to which page it belongs
  • takes every possible precaution to make it unique (without bloating it)

3.1.1 Naming pages

Page names are composed of two parts:

  1. the first part describes the category (the possible values are listed in the table below)
  2. the second part can be chosen by the user (but should be unique - for articles about applications the name of the application is recommended)
Table of prefixes
Prefix Which pages get this prefix
main Pages that are linked from the Main_Page. Usually the roots of other categories
faq Subpages of the FAQ. If it ever gets subpages
uguide Subpages of the User Guide Addendum
pguide Subpages of the Programmer's Guide Addendum
app Pages for the applications distributed with OpenFOAM. Subpages of Main_OFSolvers and Main_OFUtilities
tut Pages about the tutorials distributed with OpenFOAM. Subpages of Main_Tutorials
uguide Subpages of the User Guide Addendum
src Subpages of Main_CodeStructure
snip Subpages of Main_CodeSnipplets
howto Subpages of the How-To's
tip Subpages of the Tips and Tricks
user Page about a Institution using OpenFOAM. Subpage of Main_Users
project Page about a project done with OpenFOAM. Subpage of Main_Projects
contrib Page about an application contributed by a user. Subpage of Main_ContribUtilities or Main_ContribSolvers
example Example case contributed by a user. Subpage of Main_ContribExamples
test Testing page. Subpage of Main_TestSite


3.1.2 Naming files

Before you upload a file make sure that it's name is unique. The name should consist of two parts separated by an underscore:

  1. the first part should be derived from the name of the page on which you want to use that image. For an application this would be the name of the application.
  2. for the second part no restrictions apply (but try to make the name meaningful)

Examples of filenames would be: icoFoam_initialConditions.jpg, howtoTurbulenceModelling_screenshot1.jpg or calcThoseFunkyInitalConditions.tar.gz

3.2 Editing pages

--Bgschaid 13:48, 31 May 2005 (CEST)