From OrganicDesign Wiki
| This article is a stub. Stubs are articles that have not yet received substantial attention from the authors. They are short or insufficient pieces of information and require additions to further increase the article's usefulness. The project values stubs as useful first steps toward complete articles.
|
|
| This article is a class which is similar to a category except that it has a number of associated articles of different namespaces:
- Best practices - the concepts of Foo
- Portal:Best practices - the primary entry point for all things Foo, does section zero query of members
- Template:Best practices - articles transclude this template to designate it as a member of the Foo class
- Category:Best practices - the template will automatically categorise the instances into here, but the portal is the primary entry point
- Create:Best practices - default content which should be preloaded into newly created Foo instances
- Form:Best practices - if a forms solutions is in use, then this will be the form for creating or editing Foo parameters
|
|
When using a wiki for wiki organisation, it is important to conform to a consistent set of best practices which together make a generic wiki into a powerful organisational tool for describing, deploying, maintaining and using organisational systems. The aim of this article is to document and highlight the set of best practices we've developed over the last few years of applying organisation within the MediaWiki environment.
1 Collaboration
- Use watchlists, and set email changes to watched items in prefs
- Ensure all members are on chat together and online when editing collaborative content
2 Groups & Roles
In the following discussion we can think of roles in terms of working within an organization, and groups a MediaWiki specific concept.
Users of Mediawiki software can be members of groups which have a set of associated privileges (e.g. Sysops, Bureaucrats, and Bots).
One of the most important aspects of an organisation is the roles assigned to people. In a wiki all roles should be groups (but not all groups necessarily equate to a role). The MediaWiki groups can be associated with an article which in the case of roles would be the workspace for that role. This linking is achieved via a system message called grouppage-yourgroupname.
3 Workflow
- Job types are templates
- Todo lists should link to history (or ensure best practice of looking at history when beginning work session)
- CategoryWatch
4 Naming articles
Articles in wikis are key/value pairs where the key is the name of an article, and the value is the wikitext content. Names of articles should be carefully considered so as they are unique, and as concise as possible. This enhances article searching.
See also W:Namespace which can make up part of the name of an article.
4.1 Unique Identifiers
Some kinds of classes such as jobs or invoices are not easy to name uniquely as a product or role can be. Unique serial numbers can be made which are based on the date and time, for example, I-{{#time:Ymd-His}} which yields I-20081121-113102 or I-{{#expr:{{#time:U}}-1000000000}} which is just a plain number of seconds I-227267062.
5 Templates & Transclusion
The concept behind templates and transclusion is about providing a mechanism to dynamically pass key/value parameters to an article using transclusion. Information maintained in templates provides centralized control of the design or presentation of content independent from the articles themselves. Templates on Wikipedia allow a meta language utilizing article categorization to become quickly available via the double braces syntax.
By default the Template: namespace is assumed for transcluded templates. Articles can be transcluded by specifying the Main: namespace by prepending a : in front of articles. If an article is transcluded within another from the main namespace, the template Embed should be used to visually render the transclusion.
The underlying wikitext syntax should be as simple as possible to enhance readability and encourage modification improvements. For example using spans and div tags to format content rather than using table syntax.
Templates themselves can be categorized using <noinclude>, templates which use other templates should be categorized as doing so for organizational purposes. Extension:Treeview renders a tree structure in the right hand sidebar. Nested bullet lists should themselves be categorized articles for organizational purposes.
Template documentation could be transcluded from other templates, a common method on Wikipedia is to append
/doc to a template, and translude the documentation into the template using
<nocinclude> {{Template Name/doc}}</noinclude> e.g.
W:Template:Userbox
Templates which are themselves deigned to be transcluded with other templates should be categorized as Meta templates. Usually these are used to separate deisgn presentation and content information.
6 Categories & Keywords
Categories give articles hierarchical structure the same way that folders do for files.
- Also, articles can be associated with lists of keywords which they can later be queried by.
Articles are grouped together using the links syntax '[[', and the Category: namespace . For example, any article with the wikitext syntax [[Category:Foo]], will be categorized in the category Foo. The special page Special:Categories provides a list of all categories. Categories themselves can be created using transcluded templates, which provides a central mechanism for maintaining assigned categories.The names of categories can be organised, for example the priority categories; low, medium, high are ordinally related.
Dynamic Page List (DPL) can be used to identify all named categories in Query:Summarized categories.
7 Portals
7.1 Query's in portals
In our organisational wiki context, we should think of queries as an extension of the idea of a category in that its a dynamically generated list of articles which has some particular aspects in common as defined by the query. In the case of categorisation, this common aspect is simply that they are all members of the category in question.
Dynamic Page List (DPL) is an extension which provides parser extension functions and tags which interface using MySQL queries directly with the MediaWiki database.
- todo: Selections
- See DPL Manual for syntax usage.
- todo: queries should work like categories except that the results can render in specialised templates containing item summary or state information etc
7.2 User portals
7.3 Semantic MediaWiki
- todo: Templates as object instances using semantic annotations, see OD:SMW.
SMW fits in with our organisational paradigm very well because not only cab we look at its querying mechanism as an extension of the category idea, but also SMW extends the categorisation process itself by using a similar syntax to a category link which allows for arbitrary relationships instead of only that of category (a.k.a the "is member of" relationship).
8 Workflow
8.1 Workflow queries
Workspaces can contain lists and portals which are results of a query on a number of categories, for example a list of all the jobs which appear in both the in progress and IT support categories.
The results of these queries when specific to workflow (i.e. instances of jobs in progress, categorised by current state) are still designed to work similar to a category of articles, but they should be listed more like search-engine results containing a summary of the job parameters and in the case of content-based jobs (such as scripts or documents where the work is don in-wiki), the last items of the history should be summarised in the query results.
9 Namespaces
A namespace is a collection of pages which have content with a similar purpose, i.e. pages where the intended use is the same. Namespaces can be thought of as partitions of different types of information within the same wiki, and keep "real" content separate from user profiles, help pages, etc.
--MW:Manual:Namespace
In general, a namespace is an abstract container providing context for the items (names, or technical terms, or words) it holds and allows disambiguation of items having the same name (residing in different namespaces). --W:Namespace
Namespaces modify the name of articles using the : symbol in the article name, and are used to group certain types of articles together, e.g. all articles and their corresponding discussion (talk) pages. Namespaces are predefined in MediaWiki, additional namespaces can be added in [[LocalSettings.php]. If an article name has a ':' symbol in it, and the text before it is a currently existing namespace then it will be recognised as Namespace:ArticleName. If the name does not incorporate a valid namespace then it would be recognised as Article:Name.
See also;
9.1 Namespaces vs Category
Namespaces are like classes and represent certain kinds of real-world class of entities such as jobs, invoices, products, orders, events, processes and roles.
| *What are the advantages of namespace over categorization?
|
|
We must have a good rule about when namespaces are used as opposed to just categorisation. The rule above may not be strict enough, it could be more appropriate to say that namespaces are used for articles which are used in a certain way within the environment and that if the distinction is purely conceptual it should be categorisation.
One really important aspect of namespaces in an organisation-oriented wiki is the relationship between all articles having the same title but different namespaces. The only tight relationship of this kind currently recognised in MediaWiki is between an article and its talk page. I propose that all of the articles with the same title should have a similarly strong and defined relationship where the article title represents a concept and the namespaces are the different defined instances of that concept. Note: this rule applies really to titles which are words, not phrases such as "articles containing maths".
|
| *Main
- Summary
- Template - the structured data version of the concept
- Form
- Category - the concept's top-level workspace - in a workflow environment
- Query - See Query:All queries. This proposed namespace is for queries that are formatted as a category style list of articles. If we want alternative formats such as bullet lists for dpl queries should a template allow for the styles and the query namespace provide one such format?
- Process?
- Invoice?
- Creating new instances
|
|
10 Semantic Annotations
Semantic annotations allow templates to exhibit queryable parameters...
Annotations should not be included directly in an article, but rather within a template so that the implementation method is centralised into the template definition, rather than across many articles.
11 Summaries & Section-zero
Often documentation oriented articles have an initial summary above the table of contents (i.e. before the first section). Often it is useful to transclude these summaries into other articles. Rather than creating a separate article for the summary and transcluding that into the article, it is better to use noinclude tags or a template, to allow transclusion of the article directly but using only the summary part of the content.
11.1 Class and Instance
The <noinclude> and <includeonly> tags provide class and instance functionality to templates and their transcluded instances within articles. using <noinclude> provides information such as usage documentation to the template class, <includeonly> provides additional information to the instance, such as categorization. Note that many concepts that apply to templates such as includeonly and noinclude also apply to other kinds of articles which are transcluded such as summaries.
11.1.1 Template Categorization
Using the include style tags, categories should clearly illustrate the class/instance use of templates, for example the category Category: Template:Embed instances, and Category: Formatting templates for the class.
11.1.2 Templates vs Category
Often the question arises as to when to use a template or do it inline - usually this would be answered based on whether or not the source would need to be changed or expanded. This question becomes a bit harder to answer when the only thing in the template is a category link - ie should you always categorise with a template?
In general just a category-link would not be appropriate use of a template, but it comes down to maintenance, if it's likely that the category-link will be expanded later to include messages or security annotations - ie if your categorisation is defining a class rather than just simple grouping you would a template.
11.2 Wikipedia templates
There is a vast resource of established templates available on Wikipedia. Selected templates should be ported and categorized. A template prefix could be assigned for all borrowed templates so that commonly named templates are unique.
Anything that is ripped off Wikipiedia should be referenced and categorized as doing so, we should also have a mechanism that converts the word wikipedia to our WIKINAME automatically so we don't have to make any changes to the template article content. If changes are made and it i deemed useful to the open source community it should be submitted back to Wikipedia. This means that a 'fork of the template is less likely to develop.
12 Treeview extension
|
| Treeview renders trees of bullet lists. This is a presentation aspect of bullet list content. Currently trees can be transcluded within trees, however
Any wiki regardless of whether treeview is installed should be able to use astericks to describe hierarchical content.
Describing hierarchical should never use treeview syntax, it should only use astericks and transclusion.
Content is a hierarchical list expressed using bullet list syntax and transclusion.
We want to make sure that we do not violate the content/presentation aspect of wiktext content by transcluding trees within trees. Only bullet lists should be transculded within, trees, however for backward comptability, trees should also be transcluded within trees. The depth of the tree must be identified from the tree added to the single depth of a bullet list. |
|
13 Workflow extension
14 Bookmarks resource
Every user should maintain a structured list of bookmarks that is an html file in the format of the webbrowsers used. This allows toobars to be quickly set on any client webserver that a user has access to
15 Linking vs Embedding
Linking is the power of association in MediaWiki, creating a link or reference between the content of one article and the name of another article. External links create an association to an external resource. the advantage of this is in cross referencing concepts for example using Interwiki to link definitions of concepts to Wikipedia. Embedding of templates uses transclusion to embed content from one wiki article inside another article. The downside of template transclusion is that you must create formatting so template content can be easily identified. The formatting of content can be handled by meta-templates.
