Many technology presentations are missing something

Being a consultant and a developer, I go to quite a few technology presentations. To be honest, I rarely feel my time was well spent attending those presentations. You might feel the same, how many times have you been to a technology presentation and feel:

Everything sounds great, now what?

Or worse:

What was the point of that?

Or even worse:

That guy is just trying to sell me a bunch of stuff, I don’t like him and not going to buy anything.

I am sure the presenters intended for their presentations to be useful, so why do I walk away not feeling being helped? Here is why:

The presentation has no practical meaning to the audience

In a presentation, as an audience, I think about stuff like these:

• How is this going to save me money?
• How is this going to make me money?
• How hard is it to set this stuff up?
• How much does it cost to own and run?
• How easy and how much it costs to find help?
• How hard is to justify a viable business case to my boss/customer?
• Has any reputable businesses adopted this technologies and gained good business values? Can someone provide real prove?
• Those features looks great, but how do I make them useful?
• What now?

If the presenters just talks about features and how-to, until the above questions are addressed, the presentation has little practical meanings to the audience, in the best case, I walk away and think, “that was cool, now what?”

The real geeks need to wake up

I am a geek, I love writing code, can’t help myself. However, my view of the universe has changed dramatically before and after I started my business:

Before, when I was in the geek world

• I cared about how compilers worked in a language
• I cared about algorithm’s efficiencies
• I cared about working on “bleeding-edge” technologies and tools
• I didn’t care about customer’s budgets
• I didn’t care about the amount of time I was spending on a project
• I didn’t care whether users found my work useful “they are all dumb anyway”

After, now I am in the real world

• I care about timelines and budget
• I care about how useful the users think about my work, users are all wonderful
• I care about how to justify the project cost to the customer
• I don’t care about the purity of the logic
• I don’t care about being bleeding-edge
• I don’t care about the specs of the computer I am working on, well, almost

What I am trying to say is, there are very obvious truths about commercial IT geeks like me hardly think about, which becomes pretty apparent after you step into the business side of things:

• In most businesses, IT is a supporting activity, and often viewed as a cost, it is NOT the center of the universe
• The users are NOT dumb, they just want something useful, and they don’t care how it works, they just care it works
• The commercial IT technologies are not “bleeding-edge”, the very fact that these technologies have been commercialized means they are years behind real bleeding-edge technologies (quantum computing, DNA storage…etc).
• To the customers, usefulness is king. Real business benefits are essential. If your stuff is not useful and you can’t justify the cost, it does not matter at all, the elegance of the architecture, efficiency of the algorithms…etc

If you are a geek and presenting to the general audience, please wake up and step into the real world they live in, and address the things they care about.

What makes a good presentation

• Tell stories or case studies, real ones, with real figures
• Try to educate and inform the audience, don’t try to sell
• Give the audience the next actionable step, more materials, a web site, a program to follow up?
• Put technology features in the context of business value (save cost, increase productivity, staff retention…etc)
• Be clear about cost, how much cost and effort is required to own and use this technology, realistically
• Do not let your presentation becomes a list of product features, or worse, a technical how-to, if anyone wanted that, they go to TechNet
• Use a little humor (I know this one is hard sometimes)

What you think? Leave me your comments, appreciate it

Let me talk about my accountant for a minute.

I love my accountant! I love this guy in spite of the fact that he is not particularly cheap, sometimes he doesn’t return my calls, and to be honest, I think I can do a lot of these accounting stuff myself. But I love him for some very simple reasons:

• He always solves my problems
• I trust him, I can feel he is very skilled, I feel my money is in good hands. Interestingly, I can only really understand 50% of the stuff he talks about (this guy talks fast), but I can very clearly sense passion and skill, you can’t fake these stuff
• He is fun, when I go and see him, we laugh a lot
• I feel he looks out for my interests, when there are investment opportunities, he lets me know, so he does more than just my taxes

I know I might be able to find another accountant cheaper and maybe just as good, but I don’t care, I can comfortably afford his fees and I am having fun!

You see, my response toward my accountant has become an emotional one.

How does your customers feel about your service?

IT services tend to involve emotions, sometimes intense ones

In most scenarios, emotions will become a factor in IT services, here is why:

• In IT services, you sell people’s skills, so it is people centered
• IT services tend to be mid to long term, so there are plenty of time to develop trust or dis-trust
• Given critical importance IT systems in most organisations, when your customers put a large chunk of cash on the table and give you admin rights to their critical systems, of course, emotions run high.

The emotion side of things are never documented in any procedures or policies, but it is everywhere, and affect people’s decision profoundly.

Many IT decision makers are very busy and very confused, they need shortcuts, and their feelings are the shortcuts

All the IT decision makers in every organisations I have worked with, are faced with the same problems:

• Too many meetings, many are pointless and useless time wasters
• Too many technologies to know
• Too many vendors to manage, not enough vendors to trust
• Existing environment is a mess
• Existing process is a mess
• All of the above causes confusion and paralyzes action

So what do the smart decision maker do? They ensure they have the right people on the bus first, and then figure out where to drive it (Jim Collins, “Good to Great“). Smart decision makers do not try to understand all the details, it is impossible, they find the people who has the skills and who they trust, and delegate the responsibilities, and trust is certainly emotional.

Why do some large service organisations suck so bad?

I know some customers had very poor experiences with well known, well established IT services companies. After the customers spending tons of cash, and many painful weeks and months later, all they have to show for it is a dozen of half finished projects, which brings zero business benefits.

Why do they suck so bad? Here are some of my thoughts.

Typically, engaging a service company goes something like this:

• Customer has a business need
• Customer goes through a vendor selection process, sometimes tendering, selecting based on price, reputation and past experience. This is where the sales guys do their magic and get the contract
• The contract is signed, the sales guys move on and move out, and the engineers move in
• Now entering the long and painful journey of project managing, distrusting, blaming, misunderstanding,  change manging, mass emailing, fire fighting, compromising, re-scoping, mass emailing again…blah blah blah, all that stuff
• Emotions run high and low through out

If we look the key factors in a good service delivery, which are:

• The vendor has to care
• The vendor has to be skilled
• Then vendor and the customer must be able to communicate
• The vendor and the customer must be able to build trust

None of the above factors has anything to do with the size of the company, it has everything to do with the person(s) who is doing the project.

Love your customers, Love your staff and forget the competition

If you run a IT service company, I think you have a real chance of getting some long term loyal customers, if you understand the customer’s pain and the pillars of good services.

• Love your customers, they feed you . If you are genuine and persistent, they will feel your love and you can build trust from there
• Love your staff, they feed you too . If you are genuine and persistent, they will feel your love and give you their time, attention and skill. It is true we pay for people’s time, but they have to volunteer their passion
• Keep your skills up and keep on innovate
• Forget the competition, you have no control over what they do anyway

So, what you think? Leave me your thoughts.

In part 2, we looked at the internal structure of a help collection, and what is required to create and modify one, from high level.

In this post, we will look at some advanced topic, include:

-> context sensitive help

-> help maps

-> related help topics (those “see also” links)

BlackCompass offers a free help collection builder, to help you create, modify and deploy help collection. Get your free copy now , there are also full tutorials available.

Help context and help maps

Help collection can be context sensitive. A help context is similar to help category, they differ by the fact that, help category is a visual. Like this help category:

Multiple help topics (those links on the page) belongs to this category.

Help context is different, it is not visual. Consider this example, this url: http://senmossdev/sites/NonPublishing/_layouts/help.aspx?lcid=1033&key=antivirus will bring up this page:

What you are seeing here is actually help topic MS.WSS.ADMIN.HA10030863 (under the MS.WSS.ADMIN). What happened here is a key word (antivirus) has been associated with a help context, and help context points to this help item (MS.WSS.ADMIN.HA10030863). To accomplish this, you need a help map.

Help maps

Help maps associate key words to help context. Help maps are xml files located here <12hive>\TEMPLATE\XML\HELP

Let’s open one up and see what’s inside

As you can see, the structure is simple, for each <helpmap> node, you need to specify the key word, the help collection id, and the context Id.

The final step is to link the help context to a help page (help topic), this is specified in the help collection manifest xml. The help collection example here is MS.WSS.ADMIN.manifest, let’s open it under the <12hive>\HCCab\1033 (or other locale) folder.

In this section of the manifest, help context MS.WSS.ADMIN.antivirus is the ”relatedItemsPointingToMe” for help item MS.WSS.ADMIN.HA10030863.

So in summary, help maps link keywords to a help context, and the manifest of that help collection links this help context to a help topic.

Related help topics (those see also links)

On any help topic, you have a “See Also” section down the bottom, containing other links related to the current topic.

Lets you are on help topic A, and on this page (A), in the “See Also” section, you will a link to page B. In this case, in the manifest xml, under help item B, you will see A “pointing to it”. Consider this example:

Open up the manifest xml for help collection MS.WSS which is (MS.WSS.Manifest.xml)

As you can see, item MS.WSS.HA01161002 points to item MS.WSS.HA01161052. So on page MS.WSS.HA01161002, there should be a link to MS.WSS.HA01161052, lets confirm this. Open item MS.WSS.HA01161002 using this url: http://senmossdev/_layouts/help.aspx?lcid=1033&tid=MS.WSS.HA01161002 you will see this page:

Note the link “PV function” links to url: http://senmossdev/_layouts/help.aspx?lcid=1033&cid0=MS%2EWSS%2Emanifest&tid=MS%2EWSS%2EHA01161052

This is the end of the series on SharePoint help collection building. As mentioned, BlackCompass offers a free help collection builder, to help you to manage this process, go ahead and it out. There are also full tutorials available on BlackCompass website, showing you how to build a help collection from ground up.

If you feel there is some more unanswered questions, please leave a generous comment or email me direct Sen.Wu@blackcompass.net

BlackCompass offers a free help collection builder, to help you create, modify and deploy help collection. Get your free copy now , there are also full tutorials available.

As mentioned in the first post, the help collection cab files are in this location: <12hive>\HCCab\1033 (or other locale folder).

Let us unzip one of these cab files into a folder using winrar.

The structure of this folder as follows:

A xml manifest file – this is a file describes the help collection, it contains some meta data for the help collection and some meta data for each help item

A folder named “metadata” - this is a folder containing multiple xml files, each xml file is a metadata file describing a single help item in detail

A folder named “content” – this folder contains all the raw .htm, .js .css and image files

Lets look into each one of these

The manifest file

First note the manifest file’s name, it is <help collection name>.Manifest.xml, be sure to follow this format, make sure only use alphanumeric characters and no space in the name, to ensure smooth installation.

Open up the manifest file:

The structure of this file is simple, first, there some tags describing this help collection, such as name and author. A couple of interesting tags:

<rootCategory> – this is the “welcome” help category for  a help collection. For example, http://senmossdev/_layouts/help.aspx?Lcid=1033&cid0=MS.WSS.manifest will bring up this page:

in the above url, I only specified the locale id and the help collection id, what you are seeing is actually help category MS.WSS.CL10074787 (as specified in MS.WSS.Manifest.xml), since this is the default category.

<defaultHelpItem> – this doesn’t seem to be used, usually I just set this id to be the root category id mentioned above

<brandingImage> – doesn’t seem to be used

There are multiple <helpItem> tags , each one describes a help item in the collection, the <parent> tag is used to express a help item belongs to a help category. For example, the screenshot above shows a help category, each link point to a help item. So, in this case, you would specify the parent of the help item be the help category. The order number determines the order of the links.

Help item meta data

The metadata folder contains multiple xml files, each xml file carries metadata for a help item, each help item will have exactly one meta data file.

Lets open up a meta data file and see what’s inside:

Depends on what type of help item it is (help script, help image, help topic…), these tags may vary slightly, but they are very similar to each other. Note the naming of these files follow the format <help item id>.xml

Content folder

This folder holds all the raw content files, htm files for help topic, css files for help css, js files for help script and so on.

Note the files are named using this format <help item id>.extension.

Create and modify help collection

From a high level point of view, creating/modifying help collections involves three steps:

-> Manually create/modify the manifest xml, metadata xml or the content files itself.

-> Build a cab file of this folder structure (using cabarc.exe)

-> Install/uninstall the cab file into SharePoint using HCINSTAL.EXE

HCINSTAL.EXE

HCINSTAL.EXE is the command line utility shipped by Microsoft, used to install/uninstall help collections. You can use reflector to open it up and see what’s inside. Basically, installing a help collection is a scheduled job. HCINSTALL.EXE goes through the manifest and metadata xml file and put everything in the right place (central administration)

Type in HCINSTAL.EXE /?? in the command windows will give you advanced documentation on this tool, including all the command line parameters.

A couple of examples:

HCINSTAL.EXE /act InstallOneHC /loc 1033 /mns BC.MOVIETIMES

The above command will install a help collection BC.MOVIETIMES.cab

HCINSTAL.EXE /act InstallallHCs /loc 1033

The above command will install all help collections under the <12 hive>\HCCab\1033 folder

HCINSTAL.EXE returns an integer to indicate result, they are:

4 – OK

32 - No actions (for example, try to uninstall a help collection that doesn’t exist)

256 - Error, unfortunately, it doesn’t return what error it is. However, when you see this, check the SharePoint ULS log under <12hive>\LOGS 

This marks the end of part 2. In the final part, part 3, we will have a look some advanced topics like as context sensitive help, help maps and related help topics.

BlackCompass offers a free help collection builder, to help you create, modify and deploy help collection. Get your free copy now . Also full tutorials are available.

In this post, part 1, we will look at

-> What is SharePoint help collection

-> Where are help collections stored

-> The components of a help collection

-> The structure of a help collection cab

-> How are help page accessed

What is SharePoint help collection?

SharePoint (MOSS 2007 or WSS 3.0) has an integrated help system. On most SharePoint pages, on the top right hand corner, you will see an  symbol, click on it, it should bring up a help page, like this:

Also there are places in SharePoint where there is a link to help, like this one:

Click on the link, it will take you a help page specific to that topic, like this:

 These pages are part of a help collection, a help collection is a bunch of html pages, supporting these html pages, there are javascript files, image files, and css files. Out of the box MOSS 2007 ships 7 help collections.

Where are help collections stored

These help pages are stored in a document library in central administration. Go to your central administration site, click on “View all site content” and you will see a document library named “HelpFold”. This folder contains all SharePoint help system.

Here is an explaination of the meaning of these folders:

Content - holds htm files, these are help pages you see

Images - holds images files supporting the htm files

Lock – this folder is used by the help collection installation process, if you see entries in this folder, this means help collection installation is scheduled, this folder does not hold any help collection content

Manifests – holds manifest files of help collection (more on manifest files later)

MetaData - holds meta data files describing every help item (more on help item later)

Support - holds files supporting the help pages, such as javascript files, css files

When you install SharePoint, there is an installation process for the help system. The help system are installed from cab files.  The tool for installing help collection is “HCINSTAL.EXE” under the <12hive>\bin directory. More on this tool later.

Under the 12 hive, there is a folder called HCCab, under this folder, there are locale folders, and help collections are cab files in these folders. For example, I have an en-us installation of MOSS (locale id 1033), my folder is: <12hive>\HCCab\1033, like this:

Each one of these cab files holds one help collection, when you run HCINSTAL.EXE, you can install/uninstall help collections from cab file into SharePoint (to the “HelpFold” document library in central administration). More on this later.

You may ask, “Why not just have one giant help collection”? This is a good questions, I don’t know for sure, but as you can guess from the screenshot above, some of these help collection are intended for WSS. So Microsoft may have split up the collection for different version of the product or modular deployment of different parts of MOSS (such as central administration).

The components of a help collection

 As mentioned above, help collections are html pages with supporting images, javascript files, and images. Each of these is called a help item. A help item can be one of the following.

Help topic - htm file, which is the help page itself

Help script - a javascript file (.js)

Help image - an image file (png, jpg…)

Help css - a style sheet file (.css)

In addition to this, help items are grouped into help context and help category.

 Help category is a collection of help pages, it looks like this:

A help context is like a help category but is not used to visibly group help pages, the main use is to associate key words with a help context, and associate help context with a help item. More on this later.

The structure of a help collection cab

You can just open up these cab file using winrar.

The structure of a help collection cab file as follows:

-> a xml file named <name of the help collection>.Manifest.xml

-> a folder named meta data, in this folder, there are many xml files, each xml file contains meta data for one help item

-> a folder name “content”, this folder holds the real content (htm files, css files, js files)

All help collections are structured this way.

How are help page accessed?

Once help collections have been installed into central administration, they can be accessed from SharePoint sites. Lets pick a help page in SharePoint, take the example from above:

This is the help page talking about content approvals in document libraries (go to any document library -> settings -> versioning settings). The url of this page is: http://senmossdev/_layouts/help.aspx?Lcid=1033&Key=ContentApproval

This brings us to another interesting point, the help pages are not displayed alone, they are displayed inside of help.aspx, so help htm files are not complete html documents (does not have tags like <html> <head>…etc).

Help.aspx pages takes these query string parameters:

Lcid - the locale id of the help collection

Cid[X] - the id of the help collection, note the [X] variable is an integer, starting from 0, for example:  http://senmossdev/_layouts/help.aspx?lcid=1033&cid0=MS%2EOSS%2EADMIN%2EManifest&tid=MS%2EWSS%2EHA10021413 note this is a ZERO not the letter O. So you can cid0=[something]&cid1=[something else]

Key - the key word associated with a help context, more on help contex later

tid – id of the help item to be displayed

pg – page number, doesn’t seem to be used, if you know a place this parameter is used, please email me

Note not all of these parameters are mandetory, for example, you can just supply the tid parameter to display a help item.

How to reference help image, help css and help script from help pages

From inside of help pages, you can refer to help image, help css, and help javascript by accessing the _layouts/helpcontent.aspx page. Following is an example:

The “helpContent.aspx” takes these query string parameters:

Lcid – the locale id of the help collection

id – the id of the help image, help script or help css

ext – the file extension of the help image, help script or help css, this parameter is optional

This is the end of part 1. In part 2, we will take a closer look into the cab file, since you will be creating and modifying these cab files to create/modify help collections.

If you put a pebble in the way of an ant, the ant will first try to go around it, it tries one way, and then it tries the other way.

If that doesn’t work, the ant will try to climb over the pebble.

If for some reason it cannot climb over the pebble, the ant will try to lift the pebble, even though the pebble is hundres times heavier than the ant.

If by its own strength the ant cannot lift the pebble, it will try to get its buddies to help.

If with all the ants working together, they still cannot lift the pebble, they will start digging an tunnel under the pebble.

If all else fails, the ants will start eating through the pebble.

How long will they try? They will keep at it until they get through or the last one of the ants die.

One thing they will never do, is quitting.

Source: the art of exceptional living by Jim Rohn