Recently I dive myself in using Semantic Mediawiki on managing my software development’s features documentation. Here I want to share my first impression on Semantic Mediawiki – from understanding to really use it.
Who should read this article:
- People who are going to use Semantic Mediawiki in their wiki.
- People who are confused with the basics of it.
- People who have searched for information on the web but feel more confused.
I having been using Agile methodology on managing software development life cycle. One of the missing piece to me is documentation on new software features. I have been using Post-It notes, spreadsheet software (Google drive, Microsoft Excel), etc, but soon I found that they are all scattered around, and I am too concentrated on the pre-development documents (e.g. entities, diagrams, web page flow skeleton), further, I myself always forget the previous format of documentation, making colleagues (or each other) difficult to understand what have been done.
It makes me curious about how Mozilla manages their open-sourced project Firefox documentation, which leads me to their features page and, really impresses me. I soon realize they are using Semantic Mediawiki and SemanticForms in their wiki.
I used about 1 day (!) to understand what’s going on with it, and half another day more to use it to create my first software feature page. I would like to share my adventure on them.
I didn’t study the technical design of Semantic Mediawiki, and I have just used it for a day, so what’s described in this article is just my own understanding and may not be accurate.
What Do I Perceived Before Gettings My Hands Dirty
- I thought Semantic Mediawiki plus some extensions could allow me to create Mediawiki pages by filling some standard forms.
- When I googled for Semantic Mediawiki, it usually told you about the very popular Mediawiki extension SemanticForms. It seemed that SemanticForms is the core of all things and the only thing users will touch.
- I found the main web site of Semantic Mediawiki was really hard to understand, and it seemed that it did not have the web form which a user will interact if. I think it was teaching you another set of different mark-up language which I thought I needed not to take care since I would use SemanticForms 99% of the time (which is proven wrong later).
- I think all of the above are correct. (which kills me in the next hour)
My Misconception on Semantic Mediawiki on First Day
- I am a software developer, so I think the data/fields I filled in the forms are all saved in the database, in a separated set of tables for Semantic Mediawiki.
- I think the way I work will be like defining a form on some sort of GUI tools, and in the form I defined some “fields” like I worked on an Excel spreadsheet (Semantic: form -> fields vs Excel: form -> columns).
- I think I don’t need to learn any additional mark-up language.
- I think it is easy, should cost me 2 or 3 hours only to make things up.
- I think installation should be easy.
After 3 hours I found that Semantic Mediawiki is way hard (for me) to understand. Read on.
Big Ball of Mud
I googled like no tomorrow, searched for lots of tutorials/examples/blogs but just confused me (and maybe you too).
Here are some important resources which helped me a lot:
- http://wikiworks.com/semantic-mediawiki-vs-sharepoint.html – I never know that Semantic Mediawiki is comparable with Microsoft’s product. It raised my respect to it a lot.
- https://wiki.mozilla.org/Features/Desktop – Thank God for Mediawiki’s design such that I can know what extensions are installed on any Mediawiki and I can view the page source so I can learn.
- http://semantic-mediawiki.org/wiki/Help:User_manual – Actually I don’t want to list this page, however, I found that I re-understand what is Semantic Mediawiki in the later stage.
- http://www.mediawiki.org/wiki/Extension:Semantic_Forms/Quick_start_guide#Example – SemanticForms’ guide is actually telling you the right way to do it.
After half day on setting up the Semantic thingy, I hit my head on the wall hard for the rest of the day:
- I installed SemanticForms, and didn’t find the entry point for me to define a forms for user input.
- Finally I found that it is located in the Special:SpecialPages of the wiki (example).
- However, it introduced me the following operations: Create a class which will create a template, create category, create a form, create a property… WHAT? What is “class”? It is not found in the Semantic Mediawiki’s documentation! And the link tells me if I need finer control, I should do them separately!?
- I don’t understand why I need to take care of “creating a template” and “defining a category” while what I want is to “create a form” only, and the SemanticForms extensions’s user interface seems requiring these.
- I am unable to find a way to “define a form and lots of fields on it”.
- I am tired, I think of giving up.
Luckily I am able to figure out how. I think some of you may have the same experience to me. I recalled the line in the article “Semantic Mediawiki vs SharePoint“:
An analogy can be made to the world of cooking: SharePoint can be compared to a large set of knives you can purchase, each one for a separate task: slicing vegetables, cutting meat, cutting bread, filleting fish, etc. Because the aim is to sell these in bulk, their quality is often low; but at least you know, right out of the box, exactly which knife should be used for which task. Many experienced cooks and chefs, though, use the proverbial “one good knife” for almost everything, because once they’ve gotten used to it, it can do almost everything they need. Semantic MediaWiki is like the one knife: once you understand how it works, you can do most things with it.
So I decided to try out this “one good knife”. Read on.
Core Concept of Semantic Mediawiki + SemanticForms
In this section I want to tell you the core concept a newbie should know/just need to know about Semantic Mediawiki on first day. I highlight this line because on the first day someone played with it, he/she may be confused with the so many extensions and terms and bla bla bla but he/she’s still do not have a concept on using that.
Semantic Mediawiki’s documentation is right – it is the most important thing one should know, and also it is the easiest thing to know too. A property is somewhat similar to a “field”, a column in an Excel spreadsheet.
Simply put, a template is the “read-only” view of a Mediawiki page. Consider that: Your final output is a Mediawiki page, not a “form”. Since you know your page has structure (that’s important!), which is the reason you come for Semantic Mediawiki. In traditional Mediawiki, you already define a Template (which is built-in) to control/limit the way the user will write their page. So, your next step is to define a (semantic) template.
It turns out that SemanticForms is important too – but not as important as I think at first. It helps by rendering a web form for your to limit how wiki user to enter information (which is the most visible thing a wiki user can notice). Or in short:
A SemanticForms is just a better view of Mediawiki’ Template, by presenting it as a real form.
Isn’t it? Think of the way you write template in Mediawiki, and then use that template again and again – why not have a form thing to guard yourself from mis-input? I will be happy if the documentation can explain this eariler so I don’t need to spend so much time figuring this out.
Working on Semantic Mediawiki and SemanticForms
Define some properties first. It is found in the page Special:CreateProperty.
You are told to give a property name and the data type. Here is some tips:
- Unique name is better than vague name – For example, I am design a feature page to allow users to request for new feature. I use the property name “Feature name” instead of “name”. You can see Mozilla’s wiki for examples.
- Data type – You need to read the documentation on Semantic Mediawiki.
The most interesting thing I found (and confused me) is to declare the data type of a property by writing a special tag in that property’s page. Please re-read this sentence. By adding this text: “[[Has type:Number]]” in the property’s page (e.g. Property:Weight), the property is now assigned with a data type!! New concept? No!
Actually it is not so magical: You have done something similar when assigning a wiki page to a category, isn’t it? Just because we use that for category only, and never think about is can be applied elsewhere.
Another thing I need is that I need to restrict a property to allow only certain values only (somewhat like a dropdown box), it turns out that the Allow values thing provided by Semantic Mediawiki is the key. If you have defined that for a property, later when you are working on the SemanticForms, things will be easier.
Finally, I think it is OK if you made error on defining property, it seems that things can be changed at any time, even you have defined any templates or Semantic forms (just like the nature of Mediawiki: create, edit, edit, edit…). So, just bravely define your property!
Create the template
Next thing is to design the view of the page you expect a wiki user will see. For the view I mean the “read-only” view of the page, not the form.
When writing a template, just write it as if you are really writing a Mediawiki template, concentrate yourself on the Mediawiki markup and how to make the template looks nice.
Of course, there must be something related to Semantic’s syntax, I recommend you to:
- Create a template using SemanticForms extension, Special:CreateTemplate, to create a template.
- You don’t need to put all properties first, you can add them later.
- Learn the syntax of it by example you just created.
One note: I found that once I created a template, I am unable to modify that template with the same GUI as template creation. I am forced to add/remove properties by editing the wiki mark-ups. Luckily, it is OK.
Create the form
Since I have created a template with properties inside, things will be easy.
Go to the Special:SpecialPages and under the section Semantic Forms, click “Create a form” (Special:CreateForm). I enter the same name of the template as the form’s name. It is not required to be the same actually (there are even cases that a SemanticForms can contain multiple templates which I found later!). The SemanticForms extension will show a nice UI and list out all known properties on your specified template. Now you can adjust the properties (e.g. property is mandatory?), click save, and it is done. Again, don’t worry, you can always make correction later.
Of course life is not a life without problems.
I found that some of my properties turned to have a <textarea> for input instead of <input type=”text”>, and in the CreateForm page there is no way to change that. At the end of the day, I just create the form and edit the form page using wiki markup (by adding input=text). That’s why my perception of not needing to learn the Semantic markup is wrong.
One thing to remind you is that: A form itself has formatting too, which mean you can use wiki text to stylize your form’s outlook. Remember that the outlook of a form can be not the same as a template does. They are separated, they are two separated wiki pages.
I will not turn this article into a detailed HOWTO guide so I better stop here.
I Can’t Edit the Page Using the Form? Here is what Category Does!
A weird thing is that I can create a page using the nice SemanticForm, but I can’t edit it back using the same form! After reading this article, I now understand why I need to specify the category of the form!
In the above link, it recommends you to assign the form (which will “generate” pages) with a category, and in that category page (remember, everything in Mediawiki is a page), add a semantic property [[Has default form::<Form name>]] to it, and the “Edit with form” button will work! Think in the other way: Since all pages (in my case, software feature pages) are created by a particular form (in my case, the Feature Form), it is natural that they belong to the same category. During the way I am defining forms, I forgot to do that. However, if I think in the way of Mediawiki, I should first think of making them belong to the same category.
I would like to share some understanding of my own after my long adventure:
- It is incorrect for me to think Semantic Mediawiki as an isolated component of Mediawiki. Actually, as stated in Semantic Mediawiki’s user manual, “Semantic MediaWiki (or SMW for short) is an extension to the well-known MediaWiki software”. It is very true for the word “extension” after the hands-on experience.
- If I started everything from the point of working as using Mediawiki, and Semantic Mediawiki as a add-on support, I should reduce my learning time.
- Semantic property is the most easy concept to understand.
- Semantic template is really a Mediawiki template – it handles how your page (form?) looks. Don’t think too much, don’t be fooled/confused by Semantic Mediawiki’s documents, unless you are not familiar with the latter.
- SemanticForms is just a helper utility to edit the the view, that is, Semantic template or “template”, of the page. Most of the controls on how to input the data (e.g. mandatory, length, input type) is specified in the form, not by Semantic property.
- If you understand the way Mediawiki’s Categories feature is applied on page, then do this on the “special properties” too. This will clear out your confusion.
- At first I think the “properties” I defined will be saved to the database separately, however, I think I am wrong. To me, the data is still there – as a Wiki Page! The Semantic Mediawiki and related extensions are just interpreter, or like a mask, on the content of the page only (and that’s why it is called “semantic”).
- Defining forms is hard (or say, defining structure is hard, people tends to be not organized), but once I have created my first form, I am so happy on using that, and I don’t need to bother on the formatting (i.e. template) of the pages created. You will feel that when you started to have 3 or more pages which are similar.
After 2 days of Semantic Mediawiki battling, I started to feel the advantage of it, as well as the cleverness of the creators (plus all related Semantic Mediawiki extensions).
I hope this article can ease you on getting started on Semantic Mediawiki.
If you have any idea, please free feel to leave comments.