documentation on S Anand

HTML 4 & 5: The complete Reference

Wed, 09 Feb 2011 17:08:02 +0000

HTML 4 & 5: The Complete Reference is an iPhone / iPad app that does exactly what it says: a reference for HTML 4 and 5.

It has a list of all tags, clearly demarcated as HTML4, HTML5 or both. The application is fairly easy to scroll through to find the tag or attribute you want. Clicking on a tag, you get:

a brief description of what it’s for
what attributes are valid – the good part is you can see clearly which attributes are specific to the element, and which ones are common (like class, id, etc.). You can also see the possible values for the attribute, which helps.
and an example of how the tag is used. The examples are quite simplistic, and there’s only one per tag, but it does have a rendered version of the code, which helps.

You can also scroll through the list of attributes and see which tags they’re valid for.

The part that quite interested me was the “characters” or HTML entities. Quite often, I’d want the pound (£) or right angle quotes (»), but wouldn’t know the character or entity reference. So far, I’ve been using this HTML entity reference to search for characters, where I can just type in the word (e.g. pound or quote) and it filters the list to show what I want. I was really hoping to see that on the app, but was disappointed. It lets you search, but it’s not search as you type. And the result points you to a section that contains the character – not directly to the character. (It’s a bit difficult to find the character in the longer sections).

There’s also a section where you can see elements by “task” – e.g. Forms, Link-related, Document Setup, Interaction, etc. This is a pretty useful break-up if you’re looking for the right element for the job, or browsing for interesting new elements to discover in HTML5. (I found the <menu> and <command> tags this way.

You do have the option of just downloading the PDF version of the HTML5 spec and reading it in iBooks, of course. So while I find the book useful, without a search-as-you-type feature, I suspect it won’t do much for my speed of looking up things, so I’ll just stick to the spec for the moment.

Disclosure: I’m writing this post as part of O’Reilly’s blogger review program. While I’m not getting paid to review the app, I did get it for free.

Organisational amnesia

Tue, 19 May 2009 20:23:36 +0000

It’s amazing how much of a dependency there is on individuals writing IT systems. Reminds me of that Dilbert strip:

A few weeks ago, I was trying to figure out in what happens when there are multiple promotions. (Our client is a retailer.) I mean, if there’s a phone that costs £100 and there are 2 promotions: 10% off on phones and £10 off on phones. Do you apply the 10% off first and pay £80 or the £10 off and pay £81?

Funnily enough, the organisational answer is, “I don’t know.” The person who determined the logic is no longer with the firm. The person who wrote the code was a contractor and moved on to another project. The vendor hadn’t gotten around to documenting the code. Sure, the code’s there, and you just had to read it to figure out what it does. But no human knew what it was supposed to do.

Last week, there was a decision to rewrite some code that was 10 years old. A colleague who wasn’t quite involved in this work said, “I’m going to have to set aside 2-3 weeks for this. I wrote this stuff when I was a developer. The docs have vanished. The business owners have vanished. I’m the only one who has any clue on what it’s supposed to do.”

This week, we were trying to figure out how their store locator system works. After fiddling around with Fiddler, and seeing that it used Microsoft Virtual Earth, I was able to figure out that it identified stores near a location using a simple JSON API. But can we get the documentation around that? Nope. Tough luck. Nobody knows how it works any longer.

Personally, I don’t think this is unusual. We forget. Companies forget. But it’s usually good if what we forget is derivable. That’s how I got through my high-school physics exams: not by remembering stuff, but by being able to derive the stuff from a few principles.

Organisations can do the same. But to be able to do that, you need to have commonly understood principles. As Fred Brooks put it in The Mythical Man Month,

I contend that conceptual integrity is the most important consideration in system design. It is better to have a system omit certain anomalous features and improvements, but to reflect one set of design ideas, than to have one that contains many good but independent and uncoordinated ideas.

One of the biggest enemies of conceptual integrity is growth. Too many people too soon, and the important decisions are taken by people who’ve never had a long chat about things. There’s another reason not to grow too fast.

Comments

Kalpesh 20 May 2009 2:27 am: I guess, it should help having a debug log of things as the code is executed & the decision made in the code based on the data available. e.g. the code will put the log (conditionally) gave 10% discount, thus derived value of 90 (100 - 10) reducing $10 of the calculated value above = 80 (90 - 10) Basically, having a log of the sequence of steps, the state on which the code relies, input any function takes and output thereafter (but in a user understandable manner or in business language). One step closer to this could be writing code in a language that is relevant to business I feel we still write our code in terms of technology (arrays, exceptions, serializations etc). I don’t mean that we should not worry about those things. But, those things should be covered under a layer which makes easy for business people OR a new comer to come back to the code and read it like a specification.
Nagarjun 13 Dec 2009 10:50 am: We faced same situation while trying to find out how the comission is calculated. In the end it so happened that the commision was being calculated based on data that was 5 years old. Nobody had realised that the new data was not comin into the system :)

Laymen want documentation they understand

Wed, 04 Sep 2002 12:00:00 +0000

Programmers: learn from this. Laymen want documentation they understand. (Wish someone told me 5 years ago.)

Web Developers Virtual Library

Sat, 09 Oct 1999 12:00:00 +0000

Web design guidelines are available at the Web Developer’s Virtual Library.