Help:Design

From SNIC Documentation
Jump to: navigation, search

The purpose of this document is to explain the design choices behind this wiki and the philosophy behind its use. This is a companion document to Help:Tutorial, and it's not really meant to be read unless you have issues with what's in there, or need more words to float your boat.

Rationale

  • Our task is to provide "advanced support".
  • We need to be maximally useful to maximally many people.
  • There are obvious coordination benefits.
  • A website is an efficient one-to-many medium, so we should have one.
  • The problem is that we are a heterogeneous, distributed, multi-user editor community.
  • We still need to provide a homogeneous browsing experience to not confuse people and not scare them off.
  • We need a content management system, a versioning system, and ways of dynamically generate content.
  • This needs to be low-maintenance, because we have better things to do with our time.

Design

We have decided to go with mediawiki, which is:

  • a versioned multi-editor content management system
  • widely used, well maintained, and tested
  • open source

and can generate dynamic content using the semantic mediawiki extension and mediawiki templates.

We need all the semantic mediawiki stuff in order to be able to present something useful to our users. But at the same time we cannot design the system so that it gets in the way of efficient editing. You should be able to just get an idea and then just put it on here, without having to figure out how to do it each time, and without having to find and fill in a fat list of (perhaps inapplicable) required information in order to be allowed in.

What we have done to solve this is to define a minimal useful set of required information, i.e. we have defined a minimal set of entities that we want this website to describe (Software, Resource, Centre, Person, ...) and for each of those, a minimal set of properties to describe these with (role, description, general activities) as well as defined the semantics for their use. A corner stone in the design philosophy behind this wiki is indeed to not over-design the system so that nothing can be added at a later stage that we did not think of up front (see #Further development below). We have also defined a useful category hierarchy to facilitate queries and navigation.

The idea is that information should be entered in one specific place, not several, and that place should be obvious to find (cf. #The key to success below). Then the information can be displayed and reformatted to your heart's content elsewhere, and when the original data changes, your views will follow suit, without intervention.

Keep in mind though that since we are a heterogeneous, distributed, multi-user editor community that needs to present a homogeneous browsing experience, we do still need to maintain pretty strict editing policies so that things do not get out of hand and diverge into something useless. And that's the simple, boring rationale for our typing out all the boring stuff you find under Help:Editing policies.

The key to success

The key to success is knowing these three very simple things:

  • The wiki is entity driven.
  • You cannot edit dynamic content in-place.
  • The obvious place to enter the information on an entity is at the top of its page.

The last point is so that you shouldn't have to scour pages upon pages of running text to chase down that one tag that someone set to something a little too funky at 17:08 one Friday afternoon.

The consequence is that you will find all tabulatable information on softwares at the top of each software's page, and similarly, all tabulatable info on resources is found at the top of each resource's page. And so on and so forth. However, chances are that all you will see at the top of the page is a template, like {{software info| ... }}, but that is all right. See #What we have done to help you below.

What we have done to help you

It is of course a lot to ask that 100% of the editors should get all of this 100% right 100% of the time, so we have also invested quite a lot of work in making it easier for you to do it right than to do it wrong.

Our approach to solving this is to provide:

  • templates (=mediawikian for "functions") that:
    • fill in the right information for you.
    • generate frequently used views in site-default formats.
  • example pages that show how to use the templates.

All properties, templates, and example pages are of course documented, each in its own place as per mediawiki convention. Examples:

You will notice that all this is "keyword:name" based (or "namespace:pagename" in mediawikian), so finding relevant documentation pertaining to your current interests should not be very difficult. If it is, you should probably contact Joel Hedlund and see what's the matter.

Further development

A corner stone in the design philosophy behind this wiki is to not over-design the system so that nothing can be added at a later stage that we did not think of up front. In the current system, you are very free to set up new pages and functionality that does not fit into the current framework. The point is that if you work with what's already here, there's plenty things in place to hold your hand throughout the process, while if you decide to freeride you are more or less on your own. Depending on what you are trying to do it may be extremely easy (e.g. add a flat document about some laboratory technique) to extremely nasty (integrate a new category tree, complete with custom templated views of nested backward queries). Don't break stuff, run stuff by Joel Hedlund if you need input, we'll all applaud you if you get it right.

Retrieved from "https://snicdocs.nsc.liu.se/w/index.php?title=Help:Design&oldid=2558"