User Tools

Site Tools


webteam:draft_guidelines

Draft Wiki Guidelines

Evergreen has formal documentation maintained by the community's Documentation Interest Group but there is also a large body of information contributed by the community as a whole located on the Evergreen wiki. (A wiki is a special kind of website that makes it easy for everyone to easily add and improve web pages – learn more.) Contributing articles, guides, or tutorials to the wiki – or improving articles that others have already contributed – is a very helpful way to participate in the Evergreen community.

Creating articles in the wiki is a collaborative process. After you have written your article others may

  • Edit
  • Alter
  • Adapt
  • Add

So don't worry about making your article perfect the first time through. Don't hesitate to add content you think is useful and don't hesitate to make edits where you think you can help. There's always somebody to fix anything that breaks.

Get an account!

To get a DokuWiki account send a request to docs@evergreen-ils.org.

Posting Guidelines

Here are a few guidelines to keep in mind when using the Evergreen wiki:

  • 'Search first': Before creating a new page or making significant contributions to a page, please do a quick search to make sure that you aren't duplicating existing content on the wiki or other areas of evergreen-ils.org.
  • 'Contribute': The wiki is a resource for anyone to use. Just keep the content relevant, that is anything related to Evergreen as long as it meets our other guidelines should be appropriate.
  • 'Make improvements': If you find a typo or inaccurate information, just fix it.
  • 'Keep it legal': respect licenses and copyright. Only post content you own or provide attribution for content under a license that permits reuse.
  • 'Be nice': Keep the language clean (no swearing) and show respect for other contributors.
  • 'Respect links': Please provide redirects when you move content. Many people use the wiki and may have created bookmarks or linked to your content.

The Wiki is Public

Everything in the wiki is public.

Every edit and every new page created goes into the recent changes feed, which means that people will see your edits even if you haven't yet linked to a page.

Once it's out there, it's public.

  • Technically, administrators can delete things, but the wiki content may be mirrored, has feeds and is in the Google cache, so deleting something doesn't make it go away.
  • When you delete content from a page, the original content will still remain in the history for that page.

When you contribute content to the wiki (or edit existing content), there is a small notice that appears on the page stating:

By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 3.0 Unported

Since the wiki is a community effort, all contributions must be “licensed” to the community as a whole. Learn more about the "Creative Commons BY-SA 3.0 license" here.

Using the Wiki (How-to)

Where to start

Before creating a new page, you should first make sure that a page on your topic does not already exist:

  1. In the search box in the upper right corner, enter your topic.
  2. If the exact topic exists, the page will open.
  3. If there are related pages, you will get a search results page. Check if your topic is in the results.
  4. If your topic does not exist, choose 'create this page'.

How to edit a page

If you'd like to change a page.

  1. Make sure that you are logged in to [http://www.evergreen-ils.org evergreen-ils.org]
  2. Click the 'Edit' link in the right column.
  3. Enter your changes in the box.
  4. In the 'Summary' box, enter a short explanation of what you did.
  5. Click 'Show preview' if you want to check your changes.
  6. Click 'Save page'.

Deleting pages:

  • Pages can only be deleted by wiki admins.
  • Before you request a deletion, think about whether a redirect would be more appropriate.
  • Place pages that you would like deleted in the “Die die die” category by adding this line to the page to be deleted: {{delete}}
    • You can also specify the reason by adding {{delete|reason}} -line (where “reason” is your reason) instead.
  • Please keep in mind that any page added to this category will be permanently deleted.
  • Admins will check this category periodically and delete the pages, so don't worry if your page isn't deleted immediately.

Creating a subpage

Many sections in th wiki are organized by subtopic, like Quality/Compliance for example. There has been some confusion about how to create subpages, so here are the instructions:

  • Make sure you are logged in (and see instructions above for searching before you create a new page)
  • In the search box, type Quality/My new page name
  • Click “Go”

Please note that to avoid creating orphan pages (that is, wiki pages that no other wiki page links to) it is recommended that you create a page by linking to it first, and then clicking on the link to the non-existent page. For example Quality/My new page name. Please also note that creating sub-pages more than 2 deep is advised against, since it makes link names longer, and does not help with the maintenance of the wiki. See the Style section for the very brief style guide to the wiki.

For more information see: Signatures and Talk pages.

IMPORTANT! Namespaces!

If you add new schematics, content, tutorials etc, please make sure you put these in their own namespace. Otherwise you will flood the current namespace and maintaining uploaded files will become a mess for the users.

Usually, when you add a link to a page-to-be, you want to add your own namespace too.

You do this by using colons, and if you start your “namespacing” with a dot '.' you make the namespace relative to the current pages namespace, which is standard.

Example: Imagine that you are editing the main Tutorials page and want to add your own tutorial called “How to make a noise”. You should then link to it by using the pagename “.How to make a noise:How to make a noise” Such a name (inside a normal internal link) would put the page under the Tutorials:How to make a noise-namespace, and all your uploaded files etc would also end up here.

Please please please try to maintain a good namespace structure, it's really hard to correct it when the error already has been made.

More info: http://wiki.splitbrain.org/wiki:namespaces

Syntax and formatting

First have a look at the wiki syntax.

Try to keep formatting as clean as possible. A pages main title heading should be in H1, headings under that H2, headings under H2's should be H3 etc. Don't use horizontal rulers unless necessary (for instance they are not necessary if there's a heading right above or beneath where you want to mark a “new section”).

Example of what a small page could look like, using namespaces for sub pages etc:

====== This is the page ======

And this is the description of this page, regarding what you can find and add here etc.
Remember to use sub pages, and especially namespaces, where appropriate.

===== The first section =====

[[.Another Page:Another Page]]

===== The second section =====

[[.Yet Another Page:Yet Another Page]]

Images

You might want to include rather big screenshots within your articles, but having them displayed full size directly inside the article can make things look bad. Fortunately you can resize the image directly within the article. You can also set the alignment of the picture, examples:

Resize to given width:

{{wiki:dokuwiki-128.png?50}}

And left/center/right alignment like this:

{{ wiki:dokuwiki-128.png}}
{{wiki:dokuwiki-128.png }}
{{ wiki:dokuwiki-128.png }}

See images and other files for more info.

Code

You can insert code using the 'code' tag, like this:

<code c> float a; </code>
float a; 
float b;
a = b * 10 + 2 * sin1(x);

There's no specific code syntax highlighting.

Spell Check

Please spell check your work, either with UK or USA English.

Credit

webteam/draft_guidelines.txt · Last modified: 2012/11/21 07:03 by paxed

© 2008-2014 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.