Today the question was posed of how to break the news to a client that the project is running behind schedule.
Here are some possibilities that came to mind that readers may wish to try for themselves next time a suitable opportunity presents itself:

For the sophisticated:

I’m excited to inform you that our developers have discovered a way to enhance the application through a process not entirely dissimilar to the ageing of a fine wine. With each additional 6 months, the application is able to mature in our exquisitely hand crafted software environment thereby ensuring its full rich flavours and textures will have the best chance to ripen and mature.

For the technical:

Within the field of software development there is the concept of alignment. Whether it be to the nearest bit, byte or word, alignment allows for best chance for optimal storage and retrieval of data. Our development team have discovered that alignment can also be beneficial in other areas of development.
For example, up until this point the project has been in an unaligned state with portions of the project being delivered at seemingly random days throughout the calendar year. With a small shift in the delivery dates to be aligned to the nearest half-year, we can easily align the project to it’s optimal timeline and thus delivery a better project.

For the spiritual:

It is with great excitement that I inform you of a recent vision that out esteemed development guru had during the course of his daily healing spirits with soda and an olive session. Through his extensive connection with the wider universe (at rates which the girls assure him are easily charged to his credit for only a small fee for each additional minute), he has discovered that your project is currently in the wrong season for successful completion. The current completion date is deep within the month of the angry beetroot which is practically the worst month for software development.
He suggests it will increase your wuju, kinkles and general glub nub area if you instead aim to complete your project in the month of cheerful artichoke.

Sidenote:

There was a complaint raised that no buzzword version was included.
To be honest, I’ve always found the wide spread popularity of such terminology just plain unnerving:

He gently touched base with her. She could feel his best of breed and was lost in a realm of blue sky thinking.
Pushing the envelope, the two facilitated a synergistic leveraging of where the rubber hit the road.
"Oh George! Your paradigm shift really champions my open door policy!"
Investing in the leverage of the platform, he began proactively drilling down on her deliverables.
"Oh Enda! You are best of breed and really bring out the best practices in me!"
The baton was passed and they bathed in the postmortem glow of their skills transfer.

Continuing on from my previous post, I’m pretty certain an unnamed soul gave me a “look” earlier today. Sure, he wasn’t ever actually with in line of sight (or 10kms) of me… but I felt it deep in the “look” sensing portions of the cockles of my heart… or just slightly to the left of them anyway.

Sufficed to say, it warranted retribution in the form of some 1980’s style interactive fiction. Take that oh barer of.. err… looks?:

Loading…

The world begins as a painful dark place with loud headache inducing noises from all directions. Gravity seems to right itself and you notice that your eyes are closed.

> Open eyes

You squint against the impossibly bright and blurry world. The noise just won’t stop. All around you indistinct shapes mutter and moan. You raise your hand wearily to shield your eyes from the barrage of light and slowly things begin to focus.

> Look around

It appears to be an office of some sort. Pastel colours and plastics gently define the outline of cubicles in every direction.
All around you, people are staring in your direction. A general sense of fear or apprehension seems to present.
Other senses are starting to alert you to their presence as the body compiles its own little checklist of your state of health.
Extreme pins and needles in various limbs. Apparently where ever you had been, it wasn’t good for the circulation.
Dry cracked lips and gritty bits of sleep in the eyes. Oh well, if nothing else, at least you seemed to have slept well.
A disturbingly cool breeze washes across your body.

> Look at body

Naked. Naked and covered in some sort of grime.
Well that explains the general look of fear in the surrounding populace.
Some sort of covering would be a good investment at this point?

> Look on floor

You seem to be standing in the middle of a rather nasty collection of stains on the carpet. None of them seem to be blood coloured so there’s a good chance you can ignore them until some later point.
Just beyond the perimeter of the stains is a traffic cone, a name badge and what you can only guess was once the greater half of a hamburger and milkshake meal.

> Pick up and wear traffic cone

Mustering what you inwardly congratulate yourself with as an amazing amount of dignity for a gritty nude man in the middle of a crowded office, you meekly lean forward, retrieve the traffic cone and place it over your nether regions.

It’s at this point that you discover one of life’s more obscure lessons: there’s really no way for a nude person to ‘wear’ a traffic cone without it looking like an obscene homage to an oversized novelty codpiece.

As any hope of dignity has now safely drifted well out beyond reach, it might be worth investigating the wider world and seeing if there’s some explanation or escape from this little… situation.

> Pick up and read name badge

Another life lesson presents itself in quick succession after the last. There’s a very good reason why one never sees examples of Greek statues portraying someone attempting to pick up something off the ground whilst protecting their modesty with a traffic cone.

A collective wave of groans washes forward from the crowd in response to both your first attempt at picking up the badge… and the second attempt that, unlike the first, didn’t involve a rather nasty hernia testing entanglement with the traffic cone, your body and the floor… but did dramatically expand the number of people in the world who now have what could be described as ‘medical’ understanding of your body’s less popular bits.
(It would be later revealed that this was the exact moment that no less that a dozen witnesses suddenly decided to become vegetarians, three changed religions, two changed sexual preferences and at least one person developed a life long facial twitch every time they heard the word ‘tripod’.)

You read the name on the badge. You read it again. And again.
Just when you’re about to read it once more to confirm what your eyes are telling you, a very nervous looking man interrupts you with his best liturgical effects at a calming motion.
He clears his throat, steadies a few of his more prominent nervous twitches and wobbles and squeaks "Excuse me? Yes. Umm. Hello. My name is Jenkins. Arthur Jenkins. I’m.. um.. the office manager."
Arthur begins to reach out to begin a handshake before realising your hands are already full and whips his hand back in twitchy unconsciously over dramatic way.
A nervous cough before a studied fixation on his feet and "I.. I mean we… I mean I… were wondering if there’s anything we could.. umm… help you.. umm… with?"

> Say ‘Yes’ to Arthur

"I see you’ve recovered your name badge then" blurts Arthur in an attempt to bond with you… or at least lessen the chances of you spontaneously combusting if the amount of nervous sweat pouring off him is anything to go by.
"If you don’t mind" Arthur continues "I’ve taken the liberty of calling some people in to… umm…. assist you."

Three very large men in uniforms appear seemingly on all sides at once.

"Don’t worry" soothes one of the very large men, "we’ll soon have you all safe and sound in your very own room. Doesn’t that sound good…", he looks at the name badge held in gripped tightly in your hand, "Mr Banks?"

Gather round kiddies for I have an important life lesson to impart and the angry mob outside screaming for my death aren’t going to wait patiently forever.

The IT industry is much like the school yard or, so I’m informed by Hollywood, the prison yard. In order to gain respect from those around one, one has to take the initiative and take down the biggest kid before he or she takes down you.

It’s with this in mind that I’ve spent quite a significant amount of my time and effort insulting those around me.

Collected below for your attentive study, are a collection of some my more recent attempts to bludgeon those around me into submission:
(All typos, misspellings and vague hints at grand treason have both their rights reserved and their copyright… umm… righted)

Evidence ‘A’:
REDMOND, Washington – Feb. 4. 2010 – Microsoft Corp today announced a shift away from the IT industry.

CEO Steve Balmer was quoted earlier today as saying "For the last few years we’ve been coming up with great innovations and providing people with some really great technology but I think we can do even better. A few months ago, I was sitting at home, enjoying a peanut butter sandwich and I thought myself ‘Wow. This is a really good peanut butter sandwich!’. Literally within a minute, I was on the phone to Rob, Bob and Ray explaining how good this sandwich really was. They, of course, were equally enthusiastic about my sandwich related discovery and we began thinking of how we could harness this amazing resource for the benefit of our customers."

Microsoft will cease trading as a IT company from March 1st and move across to being one of the world’s most advanced food production companies. Customers of products such as SharePoint, Office and the Xbox 360 can now look forward exciting new ventures such as ShareNuts, OfficeDrink and the eagerly anticipated EggBox 360.

Shawn Hargraeves, one of the senior engineers in the newly formed eXtreme Nut Allergy (XNA) division explains how the transition is a natural progression for Microsoft:

"The transition is a natural progression for Microsoft."

Community Manager and Experienced Lid Opener, Kathleen Sanders, went on to explain in great detail on how she agrees:

"I agree."

Kathleen continued with "Within in our Indie games development community, we’ve been receiving request after request to stop providing great technology and start providing great mid-afternoon snacks. It’s with this in mind that we’re especially excited about our new SaaS solutions. We believe ‘Software as a Sultana’ is a revolution in the world of post-lunch-snacking."

Evidence ‘B’:
A service to my peers

As a small service to those of us who don’t have the pleasure of residing in NSW and thus attending tonight’s "Great Debate" event organised by Tim, I am forwarding a small transcript of the night’s events as predicted by scientists over the at the Readify Time Labs:

An overhead light suddenly pierces through the musty darkness from above. A crowd of sweaty figures line the spotlight’s edge.

In a slow booming voice comes "Welcome… to Tech Club!"
"I am your host, Tim Burgess, and tonight promises to be an epic battle of brains and brawn as we tackle some of the biggest questions… in manner that only we in the IT industry know how."

Two figures push slowly through the crowd to emerge through at opposite sides of the circle.

"In the red, we have the Mediterranean Mauler, …"
The shorter, more muscular of the two figures standing in the light raises his arm in recognition and gives a knowing nod of confidence to the crowd.
"a man who doesn’t know the meaning of fear… absquatulate, logomachy, unigeniture or sinistrodextral…"
He lower his hand, wriggles in discomfort slightly at the tight fit of the neon yellow mankini and adjusts the ribbon on each of his pigtails.
"a man who knows no fear and yet all lyrics to Barbra Streisand’s latest album, it’s…"
A pregnant pause fills the air.
"…Ducas, The spandex sporran of Sydney, Francis!"

The crowd erupts into a deafening circle of cheers and applause before settling once more into quite anticipation.

"In the blue corner, we have the Serious Slugger of the Shire, …"
From the opposite side of the circle, the other figure raises his hand in an equally confident gesture to the crowd.
"a man who never backs down in the face of danger, jeopardy or a really painful cramp in the calf muscle, …"
A small dismissive grunt accompanies the slow donning of the gloves and ears to complete the svelte fluffy bunny suit.
"a man who once admitted a passion for the little known off-Broadway theatre production: ‘Jar Jar Binks – A character study through mime’, it’s …"
Small gasps encircle the room.
"… Richard, The furry fists of fluff, Banks!"

The room explodes once more into an enthusiastic wall of cheering and clapping.

"Before you," the announcer bellows across the noise "are two of the legends of our industry. Each with their own brand of fighting, each with their autographed copies of ‘Balmer: An erotic tale of passion’, each with a need to win! Tonight, ladies and gentleman, is going to be a showdown like no other!"

Both contestants move to the centre of the ring. Facing each other with cold hard expressions of confidence. Both carrying a electronic buzzer in one hand and small teddy bear in the other.

Three loud metallic dings ring through the air. Each man bares his teeth in a menacing grimace. The fight is on.

Who will win? Who will return to his family with pride, honour and $20 gift certificate from Al’s House of Pickle?

Tune in tomorrow as all is revealed (not least of which, the answer to the all important question: can I run faster than Mr Francis and Mr Banks?)

Evidence ‘C’:
Musings over trading cards

With trading cards comes the image of people playing with trading cards…

The air hangs heavy over the big round table. Scattered across its surface are the long dead remains of meals and drinks past.
Around the perimeter of the table sits four players. Each discreetly peering at the competition over his cards.
No one moves or speaks. The idle pleasantries and chatter died out hours ago. Now it’s just the serious matter of the game.

A smirk creeps along the face of one of players.

"I’ll play… my ‘Mitch Denny’," he says as he slaps the card to the table’s surface.
"for it’s +4 EntLib Defensive is surely enough to see my party through the much feared Swamps of Enterprise".

The table ponders the move for a few moments before another player casually flicks a card to the table.

"Well if you’re going to make a run for it, I guess it’s up to me to remain and make a stand. One ‘Paul Stovell’ with a +5 LINQ Expression and…"
Another card drops to the table.
"… a surprise tag team attack of D20 Inversion of Control with my level 15 ‘Richard Banks’!"

"Oy! You can’t play a ‘Richard Banks’ here!"
"Why not?"
"It’s still recovering from the D20 ‘Scrumm-butting’ it suffered in the last round."
"Oh yeah…. Doh. Forgot about that. It’s armour’s still naff anyway from that brutal SharePoint’ing it received a few turns back. Oh well. Back to the drawing board."

Silence descends across the table once more for a few minutes before "…Don’t suppose you’d let me play my ‘Deadly Ducas Double Commerce Server Pipelining of Terror’ move now by any chance?"

And to think people used to worry about kids playing Dungeons and Dragons.

Here’s a little experiment for you to try in Visual Studio 2008:

• Create a project – it doesn’t matter what sort but I’m using C# console app for this example
• Add a new text file and give it the extension of .tt
• Add the following lines to it:

<#@ template debug="true" #>

<# WriteLine(“Hello “); #>World

Now if you save the file you should note that there’s a little “code behind” file hiding below the .tt file in much the same fashion as a WinForms or an ASP.Net control.

And if we open it up we can see that it the result of the .tt file being executed as if it was a template:

Hello World

So viola! We have a templating engine built right into Visual Studio and there you were just about to spend big dollars on a third party solution. Don’t you feel silly now?

Well you shouldn’t feel quite so bad… yet… as the templating engine, T4 (as it’s officially known by Microsoft as) is all very nice but it’s not quite what I’m usually looking for in a templating engine. Quite often in such scenarios, what I want to do is grab some templates, grab some data and mix them all together en masse using a funky little console app to generate all sorts of weird and wonderful files for me. T4 just looks like it’s dealing with one file at a time and, even more annoyingly, I seem to need to be in Visual Studio to use it. This just won’t do.

So how we do fix this?

It just so happens that we can host the T4 scripting engine ourselves and do all sorts of weird and wonderful things with it. The “catch” is that if you do a search through the MSDN doco or related blogs on the T4 engine you’ll come across a boat load of API stuff that can all look rather intimidating. The good news is that we’re going to be producing a working host with little to no effort at all.

(Cue fanfare)

Presenting: Luke’s ultra quick starter guide to producing your own template crunching utility!

In this example I’m going to be constructing a console app that takes a template file, a set of command line arguments and combines them together to produce a new file. It’s not exactly the most spectacular bit of technology around but it should hopefully get you on your way enough to produce you very own ultimate templating processing machine.

Sooo…. the steps are as follows:

• Create a console app project
• Track down a copy of the Microsoft.VisualStudio.TextTemplating.dll file and add a reference to it. (The MSDN docs will tell you that you can get the file as part of the Visual Studio SDK… but Visual Studio actually secretly places a copy in the GAC which you can copy to you project folder manually if you’re feeling really sneaky)
• Add the following code your Program.cs file:

static void Main(string[] args)
        {
            if (args.Length == 0 || !File.Exists(args[0]))
            {
                Console.WriteLine("Usage:");
                Console.WriteLine("CodeGen script [field0] [field1]…");
                return;
            }

            var commandLineArguments = new List<string>(args);
            var templateFilePath = commandLineArguments[0];
            var host = CreateHost(templateFilePath, commandLineArguments.Skip(1).ToList());
            var template = File.ReadAllText(templateFilePath);
            Engine engine = new Engine();
            var output = engine.ProcessTemplate(template, host);
            if (host.Errors.HasErrors)
            {
                foreach (var error in host.Errors)
                {
                    Console.WriteLine(error);
                }
                return;
            }

            var outputFilePath = Path.Combine(Path.GetDirectoryName(templateFilePath), Path.GetFileNameWithoutExtension(templateFilePath));
            File.WriteAllText(outputFilePath, output, host.FileEncoding);
            Console.WriteLine(outputFilePath + " Generated");
        }

        private static Host CreateHost(string templateFilePath, List<string> commandLineArguments)
        {
            var host = new Host();
            host.TemplateFile = templateFilePath;
            host.FileExtension = "";
            host.FileEncoding = Encoding.UTF8;
            host.StandardAssemblyReferences = new List<string>() { typeof(System.Uri).Assembly.Location };
            host.StandardImports = new List<string> { "System" };
            host.CommandLineArguments = commandLineArguments;
            return host;
        }

Most of this is quick and nasty throw away code (and not something I usually write… or at least admit to) so you can ignore most of it.

The valuable bit that is worth noting is the code that creates an instance of T4’s template Engine class, feeds it a template file along with a mysterious thing called a host and magically churns out a brand new file from it.

I’d suggest thinking of the Host as the middle man between your utility and the T4 templating engine… which brings us nicely to the next step which is…

• Create a Host class and paste the following code into it:

[Serializable()]
  public class Host : ITextTemplatingEngineHost
  {
      public string TemplateFile { get; set; }
      public string FileExtension { get; set; }
      public Encoding FileEncoding { get; set; }
      public CompilerErrorCollection Errors { get; set; }
      public IList<string> StandardAssemblyReferences { get; set; }
      public IList<string> StandardImports { get; set; }

      public bool LoadIncludeText(string requestFileName, out string content, out string location)
      {
          content = string.Empty;
          location = string.Empty;

          if (!File.Exists(requestFileName))
          {
              return false;
          }

          content = File.ReadAllText(requestFileName);
          return true;
      }

      public object GetHostOption(string optionName)
      {
          switch (optionName)
          {
              case "CacheAssemblies":
                  return true;
              default:
                  return false;
          }
      }

      public string ResolveAssemblyReference(string assemblyReference)
      {
          if (File.Exists(assemblyReference))
          {
              return assemblyReference;
          }

          var candidate = Path.Combine(Path.GetDirectoryName(this.TemplateFile), assemblyReference);
          if (File.Exists(candidate))
          {
              return candidate;
          }

          return string.Empty;
      }

      public List<string> CommandLineArguments { get; set; }

      public Type ResolveDirectiveProcessor(string processorName)
      {
          if (string.Equals(processorName, "CodeGen", StringComparison.InvariantCultureIgnoreCase))
          {
              CustomDirectiveProcessor.CommandLineArguments = CommandLineArguments;
              return typeof(CustomDirectiveProcessor);
          }
          throw new Exception("Directive processor for " + processorName + " not found");
      }

      public string ResolvePath(string path)
      {
          if (string.IsNullOrEmpty(path))
          {
              throw new ArgumentNullException("path", "Path cannot be null");
          }

          if (File.Exists(path))
          {
              return path;
          }

          var candidate = Path.Combine(Path.GetDirectoryName(this.TemplateFile), path);
          if (File.Exists(candidate))
          {
              return candidate;
          }

          return path;
      }

      public string ResolveParameterValue(string directiveId, string processorName, string parameterName)
      {
          if (string.IsNullOrEmpty(directiveId))
          {
              throw new ArgumentNullException("directiveId", "Directive cannot be null");
          }
          if (string.IsNullOrEmpty(processorName))
          {
              throw new ArgumentNullException("processorName", "Processor cannot be null");
          }
          if (string.IsNullOrEmpty(parameterName))
          {
              throw new ArgumentNullException("parameterName", "Parameter cannot be null");
          }

          return string.Empty;
      }

      public void SetFileExtension(string extension)
      {
          FileExtension = extension;
      }

      public void LogErrors(CompilerErrorCollection errors)
      {
          Errors = errors;
      }

      public AppDomain ProvideTemplatingAppDomain(string content)
      {
          return AppDomain.CreateDomain("Generation App Domain");
      }

      public void SetOutputEncoding(Encoding encoding, bool fromOutputDirective)
      {
          FileEncoding = encoding;
      }

  }

So now we have templates and a way to generate them. The thing that’s missing is a way to feed information from the outside world into the templates and the way we do this via Directive Processors. I’ll leave the fun of reading up about the specifics of these little beasties on MSDN as an exercise for the reader but here’s one I created earlier:

• Create a new code file named CustomDirectiveProcessor and paste the following code into it:

public class CustomDirectiveProcessor : DirectiveProcessor
   {
       private const string includeArgumentsKeyword = "includeArguments";
       public override bool IsDirectiveSupported(string directiveName)
       {
           if (string.Equals(directiveName, includeArgumentsKeyword, StringComparison.InvariantCultureIgnoreCase))
           {
               return true;
           }

         return false;
       }

       public CodeDomProvider Provider { get; set; }
       public string TemplateContents { get; set; }
       public CompilerErrorCollection Errors { get; set; }
       private StringBuilder codeBuffer;

       public override void StartProcessingRun(CodeDomProvider languageProvider, string templateContents, CompilerErrorCollection errors)
       {
           Provider = languageProvider;
           TemplateContents = templateContents;
           Errors = errors;
           codeBuffer = new StringBuilder();
       }

       public static List<string> CommandLineArguments = new List<string>();

       public override void ProcessDirective(string directiveName, IDictionary<string, string> arguments)
       {
           var options = new CodeGeneratorOptions()
           {
               BlankLinesBetweenMembers = true,
               IndentString = "    ",
               VerbatimOrder = true
           };

           if (string.Equals(directiveName, includeArgumentsKeyword, StringComparison.InvariantCultureIgnoreCase))
           {
               GenerateCommandLineArgumentProperties(options);
           }

       }

       private void GenerateCommandLineArgumentProperties(CodeGeneratorOptions options)
       {
           for (int argumentIndex = 0; argumentIndex < CommandLineArguments.Count; argumentIndex++)
           {
               var property = new CodeMemberProperty()
               {
                   Name = "Argument" + argumentIndex,
                   Type = new CodeTypeReference(typeof(string)),
                   Attributes = MemberAttributes.Public,
                   HasGet = true,
                   HasSet = false
               };

               property.GetStatements.Add(new CodeMethodReturnStatement(new CodePrimitiveExpression(CommandLineArguments[argumentIndex])));

               using (StringWriter writer = new StringWriter(codeBuffer, CultureInfo.InvariantCulture))
               {
                   Provider.GenerateCodeFromMember(property, writer, options);
               }
           }
       }

       public override void FinishProcessingRun()
       {
           Provider = null;
       }

       public override string GetClassCodeForProcessingRun()
       {
           return codeBuffer.ToString();
       }

       public override string[] GetImportsForProcessingRun()
       {
           var thisNamespaceElements = this.GetType().ToString().Split(‘.’);
           var thisNamespace = string.Join(".", thisNamespaceElements.Take(thisNamespaceElements.Count() – 1).ToArray());
           return new string[]
           {
              thisNamespace
           };
       }

       public override string GetPreInitializationCodeForProcessingRun()
       {
           return string.Empty;
       }

       public override string GetPostInitializationCodeForProcessingRun()
       {
           return string.Empty;
       }

       public override string[] GetReferencesForProcessingRun()
       {
           return new string[]
           {
               this.GetType().Assembly.Location
           };
       }
   }

So what does this directive processor do exactly? Well I’m glad you asked.

It allows us to extend the templating engine with our own functionality. In this case, we’re going to make it so that when some adds the following bit of code to their templates, we’re going to magically read in the command line arguments and supply them as properties:

So the only thing left to is to try it out on a template…

• Create a textfile somewhere on your machine with the extension of .cs.txt (e.g. HelloWorld.cs.txt) and paste the following code into it:

<#@ template debug="true" #>

<#@ includeArguments Processor="CodeGen" #>

<# WriteLine(Argument1 + " contains " + Argument0); #>

• Run the utility with the path of the textfile as the first argument and some random words as the second and third command line arguments (e.g. c:\temp\helloworld.cs.txt France Paris )

Hopefully you should see a brand new cs file in the folder your textfile resides in with some content (not entirely useful content I’ll admit… but template driven content none the less)

If you go back and examine the mysterious entity that is the CustomDirectiveProcessor class a little more thoroughly you may notice a few odd looking things:

• I pass the command line arguments in via static property. Yep. As it’s the templating engine that creates the instances of processors as it needs them, the only way to “communicate” between our application code and the processors is via statics. (Actually there’s quite a few ways… but this was the simplest I could think of at the time and it required the least amount of architectural magic to get it working.)
• We’re creating the properties using the CodeDom. Yep. The way the DirectiveProcessors influence the templates is via adding code dynamically. If you’re looking to do something slightly more heavyweight… or you just dislike generating code via the CodeDom intensely, there are less ugly ways to do so… but require a whole lot more time and effort than this demo warranted.

So now you know how to harness the inbuilt goodness that is the T4 templating engine for your evil purposes.

Oh… and before I forget: One last little party piece…

• Add the following line to the end of your template text file:

<# System.Diagnostics.Debugger.Break(); #>

..and rerun your console app.

If you’ve got Visual Studio kicking around you should now be looking at one fully fledged breakpoint. Yep you can break and step through your templates just like any other Visual Studio code. It even supports variable inspections. Pretty cool, no?

Now all that’s left is to go forth and template yourself silly.

Enjoy.

Whilst Readin’, wRitin’ and aRithmetic may have helped many people become the fine product members of society they are today, they generally don’t tend to appreciate being forced into doing such things in the course of learning how to play your game.

The first reason for this is the rather boring reality of attempting to read any reasonable amount of text on a television (even one of the lovely wall sized flat panel jobbies) is rarely enjoyable. If it’s any more than about six words or any smaller than around 1/10 of the available screen space in size then a lot of your users are going to either endure horrible amounts of eye strain, skip past as quickly as possible or just plain give up before they’re more than a paragraph into your amazing narrative.

Reason number two is possibly even more annoying but, none the less, just a true: People rarely read anything on a computer screen.

Oh sure they may read the stuff that they’re actively seeking or writing (such as the latest celebrity gossip or the Facebook message to the distant relative some far off land) but just about everything else is either ignored or feared. And it’s not just those luddites or generationally challenged members of your office or family either.

When was the last time you actually took the time to read a dialog window?
I mean *actually* read it.

It’s not that often is it?

Okay so if nobody is going to read anything we put up on screen, how do we inform them of all the good stuff like plot… or how play the game?

If it’s something that you want to the user to do then best way to teach them is the same way as we learn in real life: by doing it.

For example, if you want to teach the user that moving the left thumbstick moves their little avatar around the screen, why not show them the avatar on screen and let them experiment. Maybe provide a little short term goal to motivate them such as picking up an item or moving out of impending (but probably not real) danger?

If it’s something about the plot / narrative of the story that you wish top convey then text can certainly work… but it’s best used vary sparingly (think along the lines of a twitter message or less) and usually as back up for some other means such as a voice over.

Pick practically any really successful console game (from Mario through to Gears of War) and you’ll spot the signs. Very little text up on screen at any one time, Learning via experimentation and so forth.

We open this little story with David and Ducas having an IM conversation over Ducas’ choice of "why is documentation so boring?" as an IM tag line:

David Burela said: you just need to punch it up a little

David Burela said: add a little drama

Ducas said: so, explain a crud wcf service with drama…?

David Burela said:

"They had a contract which destined them to meet. Although they met and shared something important, the encounter was only a temporary connection. Although they are now disconnected from each other, the memory shall persist on"

Which tickled the fancy of David and prompted him to pose the question to the internal Readify Tech list:

Anyone else got some good soap drama between components?
A Romeo and Juliet story between C# & VB?

To which I initially replied:

C# eloping into the night with VB.Net?

I’m having trouble picturing that… although I must admit to finding the thought of a known fan of C# such as… say… Mitch… reciting the something like the following brings a small smile to my face:

But, soft! what light through yonder window breaks?
It is the east, and VB is the sun.
Arise, fair sun, and kill the envious C#,
Who is already sick and pale with case sensitivity,
That thou her maid art far more productive than she:
Be not her maid, since she is envious;
Her rampant punctuation is but sick and green
And none but fools do wear it; cast it off.
It is my lady, O, it is my love!

Me, being the big meanie that I am, couldn’t go past the opportunity to have some gentle jest with the words of one of my favourite authors mixed with a product that has consistently broken my geeky heart:

It is important to note that suddenly, and against all probability, a SmartPhone had been called into existence, several miles above the surface of an alien planet. But since this is not a naturally tenable position for a SmartPhone, this innocent creature had very little time to come to terms with its identity.

This is what it thought as it fell:

‘Ahhh! Whoa! What’s happening? Who am I? Why am I here? What’s my purpose in life? What do I mean by ‘who am I’? Okay, okay, calm down, calm down, get a grip now. Ooh, this is an interesting sensation. What is it? It’s a sort of a tingling in my… well, I suppose I better start finding names for things. Let’s call it a… pen! Yeah! Pen! And hey, what’s this roaring sound, whooshing past what I’m suddenly gonna call my screen? Wind! Is that a good name? It’ll do. Yeah, this is really exciting! I’m dizzy with anticipation! Or is it the wind? There’s an awful lot of that now, isn’t it? And what’s this thing coming toward me very fast? So big and flat and round, it needs a big wide sounding name like ‘Ow’, ‘Ownge’, ‘Round’, ‘Ground’! That’s it! Ground! Ha! I wonder if it’ll be friends with me? Hello Ground!’

But after thinking about for a while over lunch, I came up with following, slightly more serious, response:

Documentation for fun and profit

I’m a huge fan of making documentation interesting (and hopefully fun) and have no idea what the point of producing dull documentation is.

If the point of documentation is to communicate an idea then seems to make very little sense to sabotage that concept with a delivery mechanism that is actively discouraging that very act.

Imagine your intended audience. If they’re going to be struggling to stay awake during the discourse of your little phonebook style tome and resentful afterwards for having to loose a portion of their lives wading through it, what do you think the chances them actually retaining any of the supposedly important information is?

There are two objections to producing "interesting" documentation that regularly get put forward and I’m yet to be convinced by either one of the them:

The Corporate Image

The classic 1950’s "You’re here to work, not have fun! Pull your socks up! Straighten your tie!" attitude continues to haunt a lot of us to this day. We feel guilty about anything that drifts away from the stern approval of the stereotypical "bank manager" type from our (grand) parents day. If it’s fun it mustn’t be work related.

To that I say "Pfft!".

Documentation is just like anything else your company produces. It has the chance to entice, enrapture and engage your customers and staff… or it can put them to sleep.

It’s the 21st century and guess what? Nobody is interested in being bored to death by reams of tedium.

You wouldn’t dream of spending hundreds of man-hours and squillions of dollars each year producing bad advertising and marketing would you? Well that’s what a lot people do with documentation.

They spend who knows how many hours and dollars describing their wonderful new creations… in a format that so tedious and boring they may as well have just locked the product and the documentation in the basement for all the good it’s going to do.

Bob from Accounting

(Apologies for falling back on yet another bad stereotype here but I get the feeling that using geeks as a negative example would be detrimental to my cause   )

The second objection to producing interesting documentation is that not everyone can do it. Whether it’s a beautiful menagerie of Visio diagrams or a ‘page turner’ of a description, not everyone has it in them to produce interesting material.

My argument to this is: don’t make them.

Just like you wouldn’t attempt to force a dentist to fix a jet airliner engine, don’t force people who can’t write to write.

There’s little point.

At best, you and your customers survive the trip. At worst, its a grizzly mess of morale nose dived into the ground and a whirlwind of large paper doorstops scattering across the neighbourhood.

If you don’t have someone in your organisation who relishes the chance to produce exciting printed material then hire someone who does. Just like those weird brightly coloured personalities that you hired to market your wares, good technical writers are a very good way to ensure your message actually gets through to your intended audience.

So….

What are you waiting for?

Go forth and write that epic take of love, loss and the inner working of the JRX-382!

You’ve got nothing to lose and everything to gain.

PS: Yes, I too recognise the irony of someone who struggles with the whole communication thing, attempting to tell others how to communicate. Don’t blame me. Blame people like Infocom who had the temerity to demonstrate how to get away with such wild and whacky behaviour back in 1989: http://www.mv.com/ipusers/xlisper/zil.pdf