Help:Design - Revision history

Joel Hedlund (NSC): /* Design */

2011-09-20T07:35:27Z

‎Design

Joel Hedlund (NSC): /* Further development */

2011-09-20T07:33:37Z

‎Further development

Joel Hedlund (NSC): /* What we have done to help you */

2011-09-20T07:33:13Z

‎What we have done to help you

Joel Hedlund (NSC) at 07:30, 20 September 2011

2011-09-20T07:30:01Z

Joel Hedlund (NSC): /* What we have done to help you */

2011-09-20T07:29:30Z

‎What we have done to help you

Joel Hedlund (NSC): /* The key to success */

2011-09-20T07:28:45Z

‎The key to success

Joel Hedlund (NSC): /* Design */

2011-09-20T07:26:49Z

‎Design

Joel Hedlund (NSC): /* Design */

2011-09-20T07:26:15Z

‎Design

Joel Hedlund (NSC): /* Rationale */

2011-09-20T07:25:32Z

‎Rationale

Joel Hedlund (NSC): Created page with "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 ..."

2011-09-13T14:43:28Z

Created page with "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 ..."

New page

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 dynmically 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 [http://semantic-mediawiki.org semantic mediawiki extension] and 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 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. 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 of this is that you will find all tabulatable information on softwares at the top of each software's page. 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 <nowiki>{{software info| ... }}</nowiki>, 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 "function") 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:
* [[Property:General activities]]
* [[Template:software info]]
* [[Help:Application expert example page]]
* [[:Category:Example page]]
* [[:Category:Bioinformatics]]

== 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 later, 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.

@@ Line 20: / Line 20: @@
 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. We have also defined a useful category hierarchy to facilitate queries and navigation.
+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.

← Older revision		Revision as of 07:33, 20 September 2011
Line 55:		Line 55:

	== Further development ==		== 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 later, 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.	+	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.

@@ Line 18: / Line 18: @@
 and can generate dynamic content using the [http://semantic-mediawiki.org 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 to be allowed in.
+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. We have also defined a useful category hierarchy to facilitate queries and navigation.

@@ Line 51: / Line 51: @@
 * [[:Category:Example page]]
 * [[:Category:Bioinformatics]]
 == 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 later, 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.

@@ Line 45: / Line 45: @@
 * 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:
+All properties, templates, and example pages are of course documented, each in its own place as per mediawiki convention. Examples:
 * [[Property:General activities]]
 * [[Template:software info]]

@@ Line 40: / Line 40: @@
 Our approach to solving this is to provide:
-* templates (=mediawikian for "function") that:
+* templates (=mediawikian for "functions") that:
 ** fill in the right information for you.
 ** generate frequently used views in site-default formats.

@@ Line 34: / Line 34: @@
 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 of this is that you will find all tabulatable information on softwares at the top of each software's page. 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 <nowiki>{{software info| ... }}</nowiki>, but that is all right. See [[#What we have done to help you]] below.
+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 <nowiki>{{software info| ... }}</nowiki>, but that is all right. See [[#What we have done to help you]] below.
 == What we have done to help you ==

@@ Line 16: / Line 16: @@
 * widely used, well maintained, and tested
 * open source
-and can generate dynamic content using the [http://semantic-mediawiki.org semantic mediawiki extension] and templates.
+and can generate dynamic content using the [http://semantic-mediawiki.org 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 to be allowed in.

@@ Line 8: / Line 8: @@
 * 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 dynmically generate content.
+* 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.