User Tools

Site Tools


adding_articles

wiki internals - adding articles

Motivation

The information accessible at this site should be comprehensive and well structured. To achieve this, a basic structure for each article is desired.

Requirements

Please think about what information you would like to convey, and as a first step, answer the following questions:

  • in what situations will the information be useful and who is the intended reader (motivation)
  • what does the reader need to know (or do) before being able to follow the instructions given in your article
  • can the information be easily structured into a series of steps (with conditional settings)
  • do you need images (or formulae) to improve the readability and comprehensibility of the information

As general requirements (to be able to successfully create/edit a wiki page), you should have access to a web browser with JavaScript and stylesheet support, as well as a stable internet connection. If you need to add images, you might want to install an image editing program (e.g. Adobe Photoshop or The GIMP).

Suggested structure

Instruction article

As with this very article, I (and this really is just a personal preference of mine) like to follow this kind of (lose) structure when writing a manual (answering each of the questions in the requirements):

  • Motivation
  • Requirements
    • Conditional differences for cases
  • Additional background information (if required)
  • Instructions (with sub-sections for each case)
  • Examples
  • Links to articles or external sources with additional information (e.g. follow-up steps, etc.)

Reference article

Next to the instruction articles, the NeuroElf wiki naturally also contains reference material (functions, file types, UI etc.). For those articles, the Motivation and Requirements sections are obviously not (as) necessary. Hence those articles should focus on

  • Reference (e.g. output of 'help FUNCTION_NAME' in Matlab)
  • Usage examples
  • Background information (where necessary)
  • Limitations and/or caveats
  • Alternatives (if useful) and
  • Supplemental functions, material, etc.

Layout instructions

  • the header of each page should contain the top-most heading format:
    ====== Article title ======
  • the main sections (see structure) should be formatted with the next-level heading format:
    ===== Section =====
  • sub-sections naturally follow:
    ==== Sub-section level 1 ====
    Text...
    
    === Sub-section level 2 ===
    Text ...
    
    == Sub-section level 3 ==
    Text ...
  • additional information on formatting is provided on the syntax page of the wiki

Adding images

If you wish to add images (including formula representations) to the article, please refer to the articles about uploading image files and creating formula images.

adding_articles.txt · Last modified: 2011/04/05 05:48 by jochen