An art called Smart Documentation

There is no denying the fact that if there is one aspect of software engineering that gets the least importance, then it is documentation. No wonder that thoughtful people tend to advocate it all the more. We, then, in our exuberance, barf out pages and pages of text, which, even we would not have read, had it been spewed by another.

Be informed, that no software, either product or project requires end-to-end documentation. It is going to be shelved anyway. What any software needs, is a smart document. And, all a smart document will need, is a smart YOU.

I list out a few points below. Follow them at your own risk [ You wouldn't want to be called smart. Would you now? ;o) ]

• Know your audience.
  The first thing is to know whom you are targetting with your document. Is it the techie geeks within the organization; then code and design snippets would do. Is it a bunch of freshers; then you may have to allow them to soak in the details rather than throw jargon at them. Is it the business people; then be sure to outline information that needs their buy-in. If it is a bunch of dunderheads; then don't even bother; for they don't even care.
  Know that, no one document is suited for all people. It would be advisable to serve up different documents for different segments of people; rather than have it all in one single document.
  
  
• The scope
  The questions you have to constantly ask yourself is - Is the item I am writing necessary in the overall context?
  Know the scope of your document and stay within the limits of it.
  
  
• blah! blah! zzz!!!!
  In technical documents, always try to avoid long paragraphs with huge lines of text. This will do no good than to put the reader to sleep. Always look to have details put in point-wise lists. It is always easier to register 5 points with 2 lines each, than a paragraph with 20 lines.
  
  
• A picture can speak a thousand words.
  Use pictorial diagrams liberally within the document. You will be surprised at what a simple flow chart can get through to your audience than carefully worded text.
  
  
• Hand sketches.
  So now you know you have to have diagrams in your document. So that means you have to master MS Paint & Visio??? Good, if you do. If not, then just draw up a sketch with a pencil, scan and attach. The idea, is to get the message across; not to impress.
  
  
• Granularity.
  The level of granularity you go within a document is again based on your target audience. Do not burden the reader (and yourself) with unnecessary information. Stay short; be sweet; and to-the-point.
  
  
• Index
  The Document Index is one of the most important parts of your document. It gives a bird's eye-view to the reader of the content; and will also enable the reader to move to the required section swiftly.
  
  
• Indent
  Try not to have more than 2 indent levels in your document. Make sure there is minimal white space visible, and indents bring in white space.
  
  
• Use fonts wisely.
  It is always easier on the eyes if the text is consistent throughout the document. So,
  
• try not to colorize text.
• try not to have variable font-sizing within a paragraph of text.
• try to draw reader attention using italics and bold.
• try to use fonts relevant to the document. Arial is always a better choice over ComicSansMS for professional documents.
  

To end, a point to ponder!!! More often than not, lengthy documentation (or) creating a lengthy document gives one the notion of contributing/working a lot. Beware that you do not fall into the trap of false thinking. Though documentation is a good-to-have activity in any organization, false documentation only leads to productivity degradation of the individual.

JavaScript function to make an AJAX call

How many times have you had to go to the web, to look how to make a proper AJAX call? Many? Well.. Not anymore. Use this JavaScript function to make an AJAX call and process the response.

/**
* Purpose: to make a client-side request to the server, and obtain the response
*
* Input Params:
*  1. pURL - string - request URL
*  2. pPostVars - string - POST variables
*  3. pCallbackFunc - function reference - function that is to be called on 
*     successful response
*  4. pAsync - int - if request to be asynchronous - 1/0
*
* Output Params:   none
*
* Return Value:
*  on success - string - the response from the server
*  on failure - bool - false
*
* Notes:
*  1. By default the request will *NOT* be asynchronous.
*     This behaviour can be changed by the param pAsync.
*     1 is for asynchronous, and 0 is for synchronous.
*  2. By default the request method is GET. If however pPostVars is passed to the 
*     func, then the request method will be POST.
*     pPostVars will a set of post variables as
*     "var1=val1&var2=val2&var3=val3&varn=valn"
*  3. pCallbackFunc is a reference to a JS function. If specified, this function must 
*     mandatorily take a parameter to which the response string will be passed.
*  4. In most cases, if the request is going to be asynchronous, then it is always 
*     better to pass a callback function to do needful scripting after the response
*/
function GetServerResponse ( pURL, pPostVars, pCallbackFunc, pAsync )
{
var http_request = false;
var http_method = "GET";
var request_type = false;
var server_response;

if (pPostVars && pPostVars != "") var http_method = "POST";
if (pAsync && pAsync == 1) request_type = true;

// Browser - IE
if (window.ActiveXObject)
{
  try { http_request = new ActiveXObject ("Msxml2.XMLHTTP"); }
  catch (e)
  {
    try { http_request = new ActiveXObject ("Microsoft.XMLHTTP"); }
    catch (e) {}
  }
}

// Browser - Mozilla, ...
else if ( window.XMLHttpRequest )
{
  http_request = new XMLHttpRequest ();

    // some versions of Mozilla browsers won't work properly if
    // response from server doesn't have xml mime-type header
  if (http_request.overrideMimeType)
  {
    http_request.overrideMimeType("text/xml");
  }
}

  // unable to create xmlhttp obj
if (!http_request)
{
  alert('Error : Cannot create an XMLHTTP instance');
  return false;
}

  // return server output on successful retrieval
http_request.onreadystatechange = function() {
if ( http_request.readyState == 4 )
{
    // successfully got response
  if ( http_request.status == 200 )
  {
      // case : if callback function specified,
      // pass on the server response string to it as a parameter
    if ( pCallbackFunc && typeof(pCallbackFunc) == "function")
    {
      pCallbackFunc(http_request.responseText);
    }

    server_response = http_request.responseText;
  }

  else
  {
    var err = 'Error : Server returned a status code : ';
    err += http_request.status;
    alert ( err );
    server_response = false;
  }
}
};

  // GET method
if ( http_method == "GET" )
{
  http_request.open ( "GET", pURL, request_type );
  http_request.send ( null );
}

  // POST method
else if ( http_method == "POST" )
{
  http_request.open ( "POST", pURL, request_type );
  var post_ctype = "application/x-www-form-urlencoded";
  http_request.setRequestHeader ( "Content-Type", post_ctype );
  http_request.send ( pPostVars );
}

return server_response;
}