Document or Perish

by Steven Douglas Olson

Have you ever heard of Thomas Harriot?
How about Galileo?

Very few of us have heard of Thomas Harriot, yet there is evidence that he actually used a telescope before Gailileo did.

In August 1609 Harriot used a telescope to look at the moon. Four months later Galileo did the same thing. But Galileo shared his discovery to the world through publication. Harriot did not.

Harriot discovered Snell’s law of refraction before Snell did. Again, Harriot did not publish.

Galileo published his findings on the universe in The Starry Messenger just 10 days after making finishing his observations.

Last year Jesse James Garrett coined the word Ajax and described its use. I have heard any number of people saying that they have done this before, it isn't really new and on and on.

But they didn't publish the idea. They didn't share how to do it with anybody.

And that is my point. If you come up with a new idea, and want to take credit for it, share it with the world and you will get your recognition.

Writing is the technology that brought humans to the next level in advanced technology. Civilizations that prevailed in the past were literate. They could send messages, design things and communicate their ideas through their writings. For every Leonardo da Vinci there are innumerable inventors who carried their ideas to the grave. Writing is the power that can make your ideas transcend time.

Yet writing is looked upon by so many developers as a necessary evil. Not as a technology that will bring to light your application from a backroom mystical magic creation that no one understands but you.

Writing is the same as documenting in the software world. A good design document is as valuable as the source code. It is the most efficient way to communicate how the code should work. Along with a white paper describing the project, a sequence diagram, use cases and other UML diagrams can only help clarify the ideas.

Don’t talk about "self-documenting" source code and expect a developer to understand how it is supposed to work. That is a flawed premise.

First of all, communicating by source code is very inefficient.

Secondly, if the source code is “self-documenting” that means it must be bug-free. How are you supposed to know if a behavior is a bug or not? According to the “self-documenting” source code, there can never be any bugs.

Thirdly, if you document your project, it makes it easier for you to understand how things function. The writing process brings focus on your ideas and that focus may bring refinement to the project.

Finally, as people ask you how the project works, you can use your design documents to explain. You don’t have to spend your time talking about the project; you can refer them to the design documents.

This will make you more efficient and productive, and may even bring you recognition.

Reference: http://magma.nationalgeographic.com/ngm/0305/resources_who.html

9 Comments

nickpicker
2006-01-09 15:54:45
Spin
"Last year Jesse James Garrett coined the word Ajax and described its use. I have heard any number of people saying that they have done this before, it isn't really new and on and on.


But they didn't publish the idea. They didn't share how to do it with anybody."


That is untrue on so many levels that I even don't know where to start debunking it. Let me put it this way:


All essential ingredients of "AJAX" have been implemented in MSIE 5.5. When was it released? 1999? The Gecko engine followed shortly thereafter. It was clearly documented, and there were many examples, tutorials, case-studies.


However, it was constantly derided as "proprietary" and "immature" ever since then. So what changed? The technology is still proprietary (proprietary XmlHttp() in Gecko, Msxml-ActiveX in MSIE), and there are still errors in the implementations, but after the dot-com bubble and the Java (and web services and xml and ...) fad people just need a new "trend". That is all.

aristotle
2006-01-09 19:28:22
Re:

AJAX-the-techique was popularised by Google, who first recognised XMLHttpRequest as a universal enough API to build GMail (and Google Suggest) on top of it.

All that Jesse James Garnett did by “publishing” it was coin an acronym for it.

nickpicker
2006-01-09 19:36:50
Been there done that
Not true. The Outlook Web Interface had it before, and it was cross-browser, too.
steveolyo
2006-01-09 20:17:31
Re:
Right, I didn't say he invented it. I said he coined it and described its use. None of that detracts from what Google did.
Yes Ajax was used by Google before the acronymn was coined, but that was Google. Did they publish a how-to or describe their techniques in a tutorial?
steveolyo
2006-01-09 20:30:39
Spin
So your saying that all the technology has been in place to do Ajax applications since 1999, and you've known how to do it all this time? But now that the "Java fad people" have a new trend then now things are happening? Maybe the "Java fad people" with a new trend are a good thing, they apparently make things happen.


Where is this killer pre-Ajax documentation and tutorials that describe how to put together cross browser XMLHttpRequest applications dated cerca 1999?


Where are the applications that have been using it since 1999? Name names, list urls, etc.


If using XMLHttpRequest in a manner now described as Ajax was published, it's a shame that it didn't see much print or get much attention.

aristotle
2006-01-10 06:37:07
Re:
Except OWA is not a public web application.
adrianh
2006-01-11 02:11:11
Named not documented
As others have pointed out "Ajax" has been around since the XML request stuff in IE.


What Jesse did was document something that wasn't previously documented. What he did was name something that wasn't previously named.


Now I do think naming is hugely important. It's much easier to talk about Ajax than it is "you know messing with the DOM with asynchronous requests". Spotting and naming things in the coding environment gave us things like the pattern movement and Extreme Programming. But it's not documenting something that nobody else knew about.

steveolyo
2006-01-11 07:27:56
Named not documented
Good point. By naming it and describing it, plus all the attention garnered by Google, pushed the technology from a lesser known idea, to an idea that probably 99% of web programmers now know about.


The idea that Ajax presents, reached its tipping point, as described by Malcolm Gladwell in his book.


It was good timing for an article like Garrett's, and I have looked for an article that described the same ideas, but I haven't found one. It appears that his is the first, and although he didn't invent the ideas, I felt he was the first to describe it to a large audience and thus the parallel to Herriot and Galileo; one who published and one who didn't.

adrianh
2006-01-12 04:02:50
Named not documented
I have looked for an article that described the same ideas, but I haven't found one


A few minutes with Google have me http://jibbering.com/2002/4/httprequest.html, http://www.codeproject.com/jscript/refreshpartweb.asp, http://www.devarticles.com/c/a/ASP/The-Power-of-the-XMLHTTP-Library/, http://www.codeproject.com/jscript/refreshpartweb.asp - all from long before the latest rash of Ajax related stuff.