Re: Help Docs means the UI layer sucks

Oh I so agree with all you've said.

The problem is actually worse than that. Ever tried to use help? IT DOESN'T HELP!!!!

You might ask why and the answer is pretty simple. Help texts are always done as an afterthought (behind that dreaded documentation!) and the one who draws the short straw -always the same idiot- has to write it. And because he's a dimwit he can't write his way out of a paper bag.

Now Mac OS X (sorry Sky!) has good help (note I didn't say great!). It is simple and helps with what you want to know and isn't wordy. That shows to me they seem to put some effort into it. But the help files only help with about 50% of the issues that arise 95% of the time. There's no in-detail stuff. But that's OK because honestly apart from curiosity I haven't used the damn thing. Mac OS just has a lot of what you mention above. Clean design and good UI standards. A set of common APIs/UI elements doesn't harm either. So you always know where you are and what you'd want to do (there are some exceptions - yes). This paragraph should not be about boasting about Macs -again- but to show that small changes do make a huge difference.

If it is so obvious then why do most major development companies (and this is NOT only Microsoft!) still continue to churn out UI cr*p like they do? Most amasingly if you look at their Mac software they are able to develop something halfway descent...even Microsoft....and then on top of it give a sub standard help file that only has the function of tipping you over the edge when you're already stressed by not knowing how something's done.

I think the main flaw in software development is the lack of passion to do good work. Killed by stakeholders that don't care (well they do but only for $$$ aka getting their bottom line right), company regulations that stifle any creativity or improvement, not involving the developers that have to do the work in deciding how it's done, and usually customers that couldn't care less for taking the time to explain what they want.

Oh....and of course cheap! It must all be cheap! Sorry, did I say cheap?! It must be best value for money. How dare I say cheap!

Well that breeds:
1) Development of important functions only (i.e. 50% of the app that you really want)
2) Testing of the correct functionality is minimised.
3) Documentation is not done if no-one asks for it.
4) Oh and it had to be finished yesterday!
....
5) Help file????!!!! WTF???? Who does that?

And that spells C-H-E-A-P to me. No wonder UIs are carelessly designed, help is necessary but atrocious and when you are constantly aware that you have paid $$$ for this software your stomach wants to turn inside out.

It's a little like with food. You get what you pay for.

Although when I look at Open Source my argument does start to falter very quickly. There's very good OSS software out there. Must be that passion thing.

Anyway I hope that things like good industrial design, OSs like Mac OS X and gadgets like the iPhone do rub off on others to try and get their act together. When I see the renewed interest in quality goods worldwide I'm starting to have a little hope. Although it might well be that the current recession stubbs out the little flame before it can grow.

This comment might be a little wider than just help and UI but I think help and UI are the face of what's beneath and talking about them is impossible without quickly seeing the murky muck under the water's surface.

I think when we'll see that help and UI are as we'd like them then we will have realised that we are at the end of the journey and the whole SDLC is clean of the mistakes of today. Let's hope that day is soon...but don't hold your breath!

Re: Help Docs means the UI layer sucks

I won't bother with the Mac slant. Nor the OSS part. It's always fervently discussed in other places. Nor the cheap comment. That's partly true, sure.

But what I think I can and want to respond to is the spotting of the pattern that help is too often addresses as an afterthought, as a marketing issue, rather than UI issue. And if it's a pattern, then we can look for a solution.

The issue may be that currently we define input elements in C# as:

TextBox input = new TextBox();

and somewhere else, we write

Label label = new Label();

The fact that these two are tied together is not apparent, etc.

The arch of such, from a Framework side of things may be necessary, but from a UI development point of view, I think it sort of misses the point.

I've always thought that something like Martin Fowler's Two Step View Pattern , mixed with some a whole bunch of added functionality, was a stab at the right solution:

{input label="{resource:myLocalizeableLabel}" type="text" maxLength="32" validation="{resource:emailRegex}" required="true" ...etc.../}

Note: I obviously like how Silverlight added to the parsing process dynamic functionality with with its dynamic markup extensions...

And your statement that it (writing help docs) was always added too late in the game made me rethink that part of it to consider addressing the relationship between help and control earlier:

{input label="{resource:myLocalizeableLabel}" type="text" maxLength="32" validation="{resource:emailRegex}" required="true" tooltip="{...}" toolHelp="{...}" /}

Then again, that would only address controls...so still more is needed for the screen itself.

But the point I was trying to make wa that bringing forward the moment when help is addressed in the development process would be helpful. Make it as early as possible. Not just the scheduling of help being written, but its location, etc.
ie: Make the actual developer own it, while admitting that he needs assistance from someone who is specialized with clarifying intent.

Going to bed. tired and making lots of spelling mistakes.

But thanks for the comment/novella... :-)

Re: Help Docs means the UI layer sucks

OK. I'll try and lie that I understand your response. Anyway...

Making the developer write the help?! How will that ever work? to 99.99% of developers that is equal to going to prison. I think there's a space here for having the position of "IT UI designer" and "IT help documenter". These are people with unique qualifications. You're making the same mistake as everyone else. Help text or UI design is not a small pert of development. They should be equal to development and their own phase in the SDLC ad yes, they can be early in the lifecycle.

If you make developers write the help it's going to look like this:
{input label="{resource:myLocalizeableLabel}" type="text" maxLength="32" validation="{resource:emailRegex}" required="true" tooltip="" toolHelp="" /}
And only if you make the tags tooltip and toolHelp mandatory. But even then what is supposed to be in the toolHelp tag? 3 paragraphs of help description?

But even then. I'm just thinking what a customer would say if i tell him we'll need the not unsubstantial amount of $$$$$ to design the interface and $$$$$ to write a good help file. Or say yes, code needs to be amalgamated with help textx for $$$$$. And -oh- by the way we can't do functions XYZ because there's not enough budget left and time to do all this help & UI stuff. Help and UI design will be kicked immediately without even a blink.

Some hope does exist though when it comes to website design. It looks like people at least get that it might be more productive and beneficial to revenue to have a designer have at it. Probably because websites are closer to the print media. They just haven't made the connection to software yet and it's about time they do.

What we're really talking about here is the reluctance of stakeholders to push for a quality product in every way by accepting budget overruns and/or release date delays. Or the fact of proper up-front estimation for all software aspects.

But maybe I'm just being too pessimistic and blunt.

Re: Help Docs means the UI layer sucks

If you look at the tag, its not that the dev has to write the actual text -- its pointing to a localizable resource.

In doing so, the dev has to address that

a) space has to be alocated on the UI to put the ToolComment (the blob of text that is more significant than ToolTip) below the input element, and
b) that they have to write something that will express how they saw it so that the help doc person can comprehend the gist, expand on it, and make it consumer palatable.

The point is that by it a) ensures that the dev thinks about their UI layout beyond functionality space, and thinks also about the help space as being part of the UI requirements,
b) that an ongoing dialog is setup -- right from the start -- with the documentation people...that it's not immediately split into two projects (UI by one team, helpdocs by another team).
c) I agree that the argument to spend upfront on great docs is difficult to sell -- but I'm not advocating that. I'm just advocating that i) space is allocated for it, be that ii) depending on funds and time available, its hightly probable that for release 1, the ToolTips are mediocre, and per release, the in-UI help fragments are improved. The cost is an ongoing cost, not huge upfront, that can be spent in order to reduce long term tech support costs. Ie -- same effort usually applied to helpdocs, but instead of it being outside the UI, the effort is applied to the UI/product itself (rather than product #2, the helpdoc).

Look, what I'm rambling on about is: Produce help early, update often, until tech-support costs is brought down to an acceptable level...but make sure you're not side tracking yourself: work on the product, not a second product to fix product #1. The only way I see how to do that is make help comments part of the UI, not leave it a second document.

As to your second to last paragraph, not sure I like the authoritarian slant of it... There is no such thing as print or software media/design. If websites had to design according to some mythical software rules (what software? What era? Windows, Console, Terminal?), there would be no right side scrollbar, no color, and nothing wider than 40 characters. HAL, is that you?
If we applied the same constraints to print media, my daughter would have no popup-books...
A less dogmatic summary of the issue is called for... That we remember that its a product. A tool. A complex tool. A tool used not often enough that they remember every single trick. A tool that a lot of options are constantly hidden (think menus and how often people are surprised that Tools/Options exists in Word/Excel/PP/whatever...) On a power drill, they attach sticky tags to the powercable with instructions ("Don't plug this in while standing in water.") Redundant, but they know that you're probably thinking only about your shelf, the chair, your balance, and the screws in your left hand, and maybe not thinking of the obvious related information (eg, water/electricity/death).

A way of saying it is: a tool, with options, with in-proc, in-action help, rather than tooltips that obscure the screen (or worse, modal dialogs or completly separate help docs) so that our focus is linear: me-my drill-gentle voice-screw-wall-completion....rather than me-my drill BLOODY BIG INTERUPTION. PUT DOWN DRILL. LEAVE ROOM. READ MANUAL. Where was I again? Ah ye...screw...wall...HOLD ON BACK TO OTHER ROOM TO READ MANUAL...Ah yes...where was I...screw...shit. Time out. Bugger this. Lunch break.