Wednesday, September 02, 2009

Why I like Open Source documentation

I've got someone creating a structured Semantic Wiki for me at the moment and we are using Semantic Forms. One of the things we needed to do was pre-populate the fields. This means something like

{{#forminput:form_name|size|value|button_text|query_string}}

With the query string set... The documentation said

query_string is the set of values that you want passed in through the query string to the form. It should look like a typical URL query string; an example would be "namespace=User&User[Is_employee]=yes".
Now this is accurate but misses out a couple of important bits.

  1. The Namespace doesn't actually matter unless you are using namespaces (we aren't)
  2. The second "User" doesn't refer to the form name or to the namespace it refers to the template name
  3. The underscore is only valid if you actually put it in the field name yourself (i.e. unlike other bits in MediaWiki where "Fred Jones == Fred_Jones" that isn't true
So after a bit of randomly focused hacking I found the solution.... and what did I do. I updated the documentation to add
The format of a query string differs from the form_name in that it uses the template name. As an example if you have a "Person" template (Template:Person) and a Person Form (Form:Person_Form) for entry then it is the names from the Template that matter. An example to populate the Home Telephone field would therefore be: {{#forminput:PersonForm||Add Person|Person_Form[Home Telephone]=555-6666}} N.B. The FORM uses underscores while the field uses spaces.
Now this could be written better I agree, but the point is that the next poor bugger through will now have a better starting place than we did. Adding examples is something that is particularly useful in much documentation and something that is often missing. I regularly find myself Googling for an example after failing to understand something that the person writing the documentation clearly felt was beneath them to explain.

For commercial software you'd clearly like to see a bit more of an editorial process to make sure its not stupid advice like "Install this Malware", but its an area where more companies could benefit from improvements in customer service and self-help by enabling people to extend their current documentation in ways that better fit how end-users see their technologies.

3 comments:

Colin Jack said...

"Adding examples is something that is particularly useful in much documentation and something that is often missing."

Couldn't agree more.

Skew said...

I also agree, but I'm having problems understanding your example, between PersonForm, Person_Form, Person, and Person_Form[Home Telephone], the latter of which I thought was supposed to be a template.

I'm going ahead and doing permutations based on your sample, but do you have the exact line available that uses your givens of Template:Person and Form:Person_Form?

Skew said...

I also agree, but I'm having problems understanding your example, between PersonForm, Person_Form, Person, and Person_Form[Home Telephone], the latter of which I thought was supposed to be a template.

I'm going ahead and doing permutations based on your sample, but do you have the exact line available that uses your givens of Template:Person and Form:Person_Form?