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.

Be clear - document

A number of years ago I had a period of time working at a smaller company where I found myself up against the massed ranks of the "big american consultancy" (BAC) on a number of projects. Now clearly they didn't like me as I was doing some high value delivery work and might have occasionally pointed out some minor flaws in the way that they were working. Now what this did teach me however was the following

1. Don't delete any emails
2. Always send a summary email after a meeting even if it isn't full minutes
3. Document decisions - if someone decides something then send them an email confirming the decision
4. Point out the obvious - if someone changes their mind. Point it out to them. If they are a senior stakeholder then do this one on one. Even if they do change their mind then at least they'll feel that they owe you one. If they are competing against your project then make it visible to everyone.
5. Don't rely on a conference call to get you the status. Build up a social network and trust to the water cooler conversations
6. Go to the raw data. If its about development then do code reviews, if its about data warehousing then go to the data quality and volumes, if its about user interfaces then go to the usability studies.

Now what I'm not advocating is lots of massively verbose documents, in those lie doom as the detail is where the weasel professors can live. The important piece here is making documentation clear and small. One notable experience I had with a BAC was where they refused to do Unicode as it was "too hard" for their mainframes (this is despite pointing out that UTF-8 is basically an extended ASCII set) so we went to the standard ASCII set. Testing began and the data had what looked like typos all over the place. Clearly this was an integration (my) problem. But thanks to the very brief documentation we quickly proved that they were sending an 8 bit character set through when ASCII is 7 bit. Oddly the decision was then to move to UTF-8.

The point on documentation is short, sharp, concise and irrefutable. Its there to make decisions visible and obvious and make non-adherence to those decisions an act of wilful stupidity or disobedience.

As a client said to a BAC on one of my more entertaining projects.

"Are you a complete idiot or an asshole?" (it was an American project)

Documentation isn't there to hide behind (CYA) its there to document facts and Just the Facts.

Technorati Tags: SOA, Service Architecture