Wiki Documentation Standards

From Open Source Ecology
Jump to: navigation, search

Merge icon.png It has been suggested that the text below be merged into (added to) the Wiki_instructions#Policies page. (Discuss)

Introduction[edit]

As the number of contributors to the OSE Wiki is growing, it is time to begin defining standards for content. Wikipedia is a good example of clear formatting and standards. Our standards are by nature more demanding, since we are not only re-presenting knowledge as Wikipedia does, but also developing/inegrating designs at the same time. A collaborative multimedia strategy for accomplishing this task successfully is yet to be defined and perfected. Our aim is to start this process, and make significant contibutions thereto.

On OSE Wiki[edit]

Todo items for wiki development:

  • We need some kind of template flag to place at the top of the main page for each tool, to show where it lives in Development Work Template process. (a couple of days work).
  • We need to install semantic media wiki extensions, and refactor pages to include semantic links, which will help us bridge our work with the work of others in an open way (and allow a bridge between OSE Drupal and OSE Media Wiki, and other projects. (probably a 1 to 2 month project, if 4-5 people help). Also, within the wiki, this would allow us to flag dependencies in logical ways. We would need to analyze and create a realistic workflow for this. We can also help other wikis participate in LinkingOpenData in this way (like appropedia). Then, we can start to build open source web applications that can let you logically combine data from multiple locations, and output a unique collection as pdf, a repository, a new wiki, etc.
  • Invite some volunteers to help with the above.


Using Category[edit]

Media wiki offers an affordance that allows exporting whole collections of pages by category. Pages in media wiki may have multiple categories. So, we should use category both in the way that it is being used now, plus


Workflow[edit]

One mistake that Wikipedia makes is to make ambiguous rules that people then use as a foundation for different agendas.

Therefore, we need a *fair*, objective criteria for quality of articles:

1: No deletion (unless page is total spam). Space on OSE wiki is cheap. It is better to keep a page, and edit it, than to delete. Category system can be used to map pages that are considered to be part of specific collections (like actual projects in progress vs an idea).

2: We should use a system of flags at the top of pages that let people know what needs to be done.


Criteria could be:

  • Content should follow OSE Specifications for replicability and ecological design
  • There is a clear statement of purpose
  • There are verifiable references to any claims made
  • Templates are used where applicable
  • pages maintain higher quality when they have maintainers. So, a page should list declared maintainer(s). These are the people who are responsible for creating, and upkeep of the page.
  • please list anything I may be missing here...

Exporting from wiki[edit]

(draft in progress...not complete)

Structure your work stages according to Development Work Template.

For each stage, first document text on wiki, as described above. This will allow others to work with you on text as project develops.

Click on Printable Version in left sidebar, right cick on page and save as "pagename.html" where pagename = the name of the wiki page.

Download Python http://www.python.org/download/releases/2.5/

Download Mercurial http://www.selenic.com/mercurial/wiki/

Place all of your files into a folder (this folder will be the project's working copy)

navigate to that folder in your terminal (or Putty terminal in windows).

type "hg init"

This is will initiate the files into a repostiory of their own

Type "hg add", which will add your files to the repository.

Type "hg ci -m 'you notes and messages here'


Also usable: http://www.selenic.com/mercurial/wiki/index.cgi/OtherTools GUI clients for mercurial.


..more to come