User Guides

old_fart_mode = on

They don’t do user guides as they did before… When I was young the manuals were clear, easy to understand and really, really helpful. Not how they are today…

STOP!

old_fart_mode = off

Stop, old fart, You don’t know what You are babbling about!

What f*ng user guides?!

Exactly.

There is no point complaining about a quality of something what doesn’t exist anymore.

What is a user guide?

For anyone who is older than, let’s say thirty this looks like utterly stupid question. But for Younger generation I think it is important to explain what the user guide is. Or rather what it was.

I suppose when You are reading it You start thinking that I am an utter idiot. Sure, I am. But before You leave just think: have You seen a full blow user manual for any commercial software You used during last, let’s say ten years? Fifteen? Twenty? Well… maybe twenty years ago You might have seen it.

So what the hell is a user guide?

First step: User guide is a book.

It may be on paper or it may be in an electronic form. It doesn’t matter. What matters it is that it is a book and it is obliged to behave as a book. This means it must be easy to read, must use clear language. Must be easy to understand.

Every requirement of good novel must be met, except, maybe, the flexibility of the language. Story must flow, the gun must be hung on the wall before it fires. And anything like that.

All right, so once You know what user guide was now it is a time  to ask Yourself: What it was used for?

What is user guide used for?

For a carpenter hammer is to hammering a nail. For a nail a hammer is something used to be beaten in a head. This means that the answer to above question will strongly depend on from whose point of view we are looking at the problem.

Whom is user guide for?

This is very important to understand, that user guide is for…. well…. the user. When You write a user guide for Your company software remember this is not a book written for an internal use. There is no “everyone knows what  <enter any important program function here> is”.

A user guide is for a user. Or, what is even more important, for a future user. And future user has one very important property: they do not know anything about Your program. There may be obvious for You that RHINO is…. hell if I know what it is…. but for anyone else it will be a damn big animal what loves bathing in the mud.

User guide tells user what this software is useful for.

This may again sound stupid, but many manual writers do forget about it. Try for an example a manual for mockito Java library. Starting from the first sentence the are telling You how to mock, how to make a mock, hot to use a mock, and how much mocking will help You. I had lost about three hours, which included looking into its source code to understand what the hell is “mock” anyway.

This kind of user manual is a pure form “customer repellent”. If Your future user can’t understand after reading a page or two what is this software for, then how can You expect them to buy it? One working hour costs about, let’s say 30Euro. Do You honestly expect Your future client to spend 50Euros to understand that this software is not for him? Sure it may be worth for a selection of 5’000Euro software, but for anything around a thousand it is naive.

Remember, Your future user must select Your software from tens of available solutions!

Ok., so Your user read an “Introduction” chapter and now understands that this software may be for him. What is the user guide used then?

User guide allows to avoid costly trial-and-error usability validation

This day I tried to install on a smartphone something what will allow me to record the phone call. This kind of activity is fully legal for a private person in my country. My old Nokia phone has this function. This new smartphone advertises on the Samsung support page that it has it, but this function may be not available in some countries.

Notice the underlined may be and some.

So does this smartphone have it or does it not?

The only way, according to Samsung, to gain this knowledge is to spend 500Euros to buy this phone, check it, return and hope for a refund… Nice, isn’t it?

So I tried a google phone app. Again You may find on support page, that to get this function You must have Android 9+ and newest version of the application. Fine, no problem…. except that after spending a lot of time on downloading it, after allowing it to crawl all the data on a phone it appeared that this function is not there anymore.

If both the smartphone and a phone app would have a well made user guide I would know it from a scratch and stay with my Nokia phone.

The good user guide allows Your future user to decide, if Your product fits exactly his/her needs. Not just may in some countries but it f*ng do!

User guide explains how to do things…

So what I would be looking for in that above mentioned non-existing user guide?

I am a very, very accurate person, so I would have skipped the “Futures” chapter and  look for a chapter called “Recording phone call”. I would look into it and check how to do it. I would possibly find there some information where the recording is stored and in what format. If there are any limitations there is also probable that they would be explained there…

….in every f*ing detail!

And I mean it. With screenshots, colors and etc. That damn button does it when You touch it. That empty space, when You touch and hold it will do something else. And if You try to wipe left to right that mugshot on the top the phone-book entry will appear.

User guide save user spending hours on “discovering functions”

“Discoverability” of a user interface is a myth which stands behind the idea of “flat user interface”. Flat equals to: active and inactive elements do not differ.

If You read this blog, which is using a ready-made template without me being able to tune it, You will notice at the top gray “Main“, “Blog” and “About“. Below You will find equally grey “software quality and concepts“.

Do they differ visually?

Not much. At least not for me. They are all gray text, are the not?

Except, that three first are active and the last is not.

Gladly the designer of this template was not an utter idiot and made those elements to react on mouse hoover over it. So if You will try to move mouse around every damn object on a page You will probably find what is active and what is not.

I let myself to underline try to move because unless You will try to do something You won’t even know that there is such a possibility hidden up there.

Sadly not every one is so smart as this author was.

Never less did You try to hoover Your finger over something on the smartphone? It never works for me.

And what if “flat” is moved to an extremity, as at deviantart.com page where an empty space reacts on mouse click? Obviously with this style of design to be able “discover” all functions You will have to end up left clicking, right clicking, dragging, tapping, nipping, wiping and pushing every damn inch of the screen to make sure that You did not miss anything important. And remember, on PC You also hava a 100+ keys on keyboard which can be pressed in (100^100)^10 combinations cause You have ten fingers.

I am not against “flat” design. If fashionable look is very, very….very^infinity important then it is a must. I have nothing against top left empty corner to react on mouse click when there is some text selected providing I can read about it without spending hours on searching over the net.

“Discoverability” is a madness and a good user guide may save countless tens of hours of work and frustration.

And, apparently, save a life of a smartphone which may not survive to be thrown out of the window from fifth floor.

Three kinds of users

There is one more thing to remember about a “user” the manual is for. That there are three of them, which do stand in order of appearance:

1. Future user, who needs to know if this product will met they needs.
2. First time user, who will learn, step by step, how to use the program in most efficient and proper way.
3. Returning user, who used program some time ago, but just this damn damp day is too hot for him/her to remember how it was done and where this damn button is hidden.

The all need Your manual, but they need it for an another reason and will use it in a different way.

Summary

In this blog entry You might have read some obvious things. For some of You it was so obvious and boring, that You just clicked away. But for some of You it might be an eye-opener into a land of a software which is not only nice looking, but also easy to find, easy to learn and easy to use.

In next blog entry I will try to switch a side and explain why there are no user guides anymore and why You, a software company owner (or in fact: any company owner) should do absolutely everything to prevent Your employees from creating such an evil thing like a “user guide”.

Hello and welcome!

What will this blog be about?

In most generic words: about software. And about what annoys me in it most.

But since I’m a software and hardware engineer I will always try to wrap everything around both user experience and coding.

Since it is a blog form I suppose I should say something about myself.

I do belong to the second generation of programmers, that is I started my adventure with computers from the ZX-Spectrum. If You don’t know what was that ask wiki. This was a simple 8-bit machine with 48kB (yes, 48 kilo-bytes) of RAM in which user code may sit in. In standard it had a tape interface which linked via a standard audio channel with Your tape-recorder. Gladly I got my hands on ZX-Spectrum clone, the TIMEX-2048 and I was able to get a floppy disk drive for it. This kind of setup allowed me to efficiently start learning how to write programs. At this time I focused most on built-in Basic and Beta-Basic extension. I was still too dumb to go down to assembler what was a next step in that era. Notice, C, Pascal and etc. where out of question due to the very limited resources which had to keep in a memory both compiler, source code and produced executable.

Then my school bought a network of Elwro 800 Junior machines. Those were Polish clones of ZX-Spectrum, about ten times that large, but with more RAM and built-in networking capabilities. When networking was on they could run a clone of a CPM operating system and connect with a floppy drive which was attached to a “server”. As CPM allowed to use the vast amount of 64kB of memory, they were capable of running compilers. So at this time I started with Pascal.

The political context of those time in Poland was a decline of communists party. The economy opened and many individuals focused on gaining profit. Yet the large companies were falling apart or staying behind. At this moment the government decided to completely ignore the electronics market and leave it on it’s own. Most Polish companies which were capable of producing electronic elements (transistors, analog and digital chips, computers) went down to sewer. Very soon anyone who tried to play with electronics became completely dependent on the import.

There was however one key component in Polish government policy which skyrocketed the computer business: the lack of intellectual property rights for software. Yes, you read it right. The lack of it.

At this time the value of our currency was extremely low. Many people were traveling to West-Germany for work. In most cases they were working well below their qualifications yet they earned about ten times in value what they could earn here in Poland.

This was a context in which intellectual rights has to be seen. The 100$ for software was not much for western people who produced it. Yet we simply could not afford it. Notice, this problem is still present. The annual licenses for CAD software the company I work for is using are charged at the level of about three months worth of employee payment. If a private person would like to buy it this will in most cases consume all the annual savings.

But let go back to history.

So there was no intellectual property protection for software. None. Zero. So we copied everything we could. There were even shops which could do that for a small amount of money. They were keeping a stash of software, even had printed catalogs, and You could go there and buy a copy of whatever they had. There were even weekly fairs on which You could exchange the software with others. And by “exchange” I mean “copy”.

In the era of 8-bit so called “home computers” most of such exchange was focused on gaming. Those small systems were simply not powerful enough to do any useful job for adults so kids were main market. And we were gaming a lot learning in a background about electronics and software.

The next era started with a PC. An 8088 or 8086 Intel CPU based machine usually with 256kB of RAM (up to 640kB what was a hardware limit) and floppy disks.

Those machines were totally useless for kids. A gaming experience was so poor that we rarely used it. Yet when a hard disk was added to a system, a good keyboard and a spreadsheet software it became a working horse for medium business accounting. Lotus, Quatro-Pro and Framework where three applications which made it popular and useful. Some even tried to play with CAD software but at this time it was hard to get hands on it and it usually required far to strong hardware.

So the next work horse for PC was AutoCad. This software was at that time as bad as it is now. It was sloooow. Getting a coffee break while it was redrawing and image was a popular case. Click, get to coffee. Click…. click… Yet it was way faster than piece of paper and a company which owned a plotter ( a kind of XY rail system with a pencils set which could draw in ink) could replace about ten employees with one such system.

AutoCad was popular. The equation CAD==AutoCad was burned in our minds very deep. However the main reason for it’s popularity was that it was not efficiently protected and You just could copy it without any problem.

Then I got my first PC. It was 80286-16MHz 1MB system with 1024×768 256 colors graphics adapter and a tiny 14-inch display. It had huge 40MBytes hard disk. This could run most games (I was still a kid then) and could run some useful software.

Next step of my computer history was the introduction of MegaCAD at German market. It was a small company which created a CAD software which was about ten times as fast as AutoCad on the same machine and about ten times as much easy to use. This became my work-horse for my school jobs as at that time I was learning in middle school for mechanics. We were both learning how to work using machines and how to design them.

This was a first time when I was confronted with software quality. But since I didn’t code much yet I just could tell that there was a brilliant software (MegaCAD) and garbage software (AutoCad).

This was the era of Pascal in my computer education. To be specific – an object Turbo Pascal. I learned about Turbo Vision, virtual methods, objects and etc. I made my own GUI library and wrote as a middle school diploma a software tool for computing mechanical elements. I was very proud of it because I designed it in such a way, that it was working like a “magic form”. User clicked: “I like to calculate a gear” and a form appeared with some drawing and data. User just filled data he knows and clicked “compute”. The program then filled the missing fields. Even up to now it is rare to find such user interaction model.

By the way, ask Yourself which company have won? Autodesk or MegatechSoftware? Better or worse?

I went to high school. The Poznań University of Technology.

In terms of history it was 80386 era, but due to financial reasons I have fallen back to 8088. My dad and brother needed a computer too and the small Schneider PC thrown in Germany to the garage sale was all I could get. I was staying in kind of backward shift in computers strength until about ten years ago when for a first time I bought best machine which was on the market. And I am still using it. Right. So I’m still held back.

At this moment I started to play with C++.

My first impression was: “what a crap!”. The language was messy, but at this time I did not care about much. The worst impression was the compilation time. With Turbo Pascal I just pressed F9 and within a second or two I got a program running. With Turbo C++ it was taking about ten times of that time.

But hey, it had many great features. It had multi-base inheritance, overloaded operators and so so many more.

Guess what? I abandoned it in my work. I can do it, but working with C++ is for me like driving an F1 car. I drive my own real car about once a month, so You may imagine what would me driving F1 look like: wrrrr…. zippp… crash.

At this time I played for a first time with genetic algorithms. And fell in love with that. The reason for my still standing love for evolutionary algorithms is not the fact that they are in any means a miraculous tool to solve every problem. It was their robustness. I wrote a program which was using a genetic algorithm to solve something. Due to some memory limitations it needed some assembly code to gain access to so called EMS memory (DOS era, 80286/80386 way of switching 64kB window of RAM and move it around all the memory). And I totally screwed it. It wasn’t switching those memory pages as it should. Yet the algorithm solved a problem.

Amazing, isn’t it?

Later in my work I learned how amazingly well “probabilistic algorithms” can behave.

Somewhere in a middle of my high school I went even more backwards. Back to 8051 Intel micro-controller. I played with an Atmel flash based clone of it. It was a tiny 8 bit CPU of a very strange architecture, but needed to run only a power supply and a quartz crystal. It could have been programmed with parallel port (the old printer port present then on every PC) with a simple pin-toggling. This kind of device could be programmed in C, but to gain most of it one really had to go down to assembler.

And then my programming path have split. On one hand I was getting deeper and deeper into micro-controllers. 8051, AVR, PIC, MSP430. On the other hand I had to create applications on PC which cooperated with devices I made. So I first tried to get back to Pascal, but a the rise of Windows era it totally lost any kind of good support. Then I tried the C++, but again it was a mass failure. Yes, the application works, but the fact that some serious memory leak bugs had sustained in it undiscovered during 15 years was a real let-down.

And at least I discovered JAVA. As a low-level embedded programmer at those days I started discovering it from reading virtual machine specification. The micro-controllers world taught me that any programming language can do efficiently only what a CPU can efficiently do. Yes, sure, You can force PIC-16 to do an indirect call, but if You take a look at assembly… o gosh….

Java Virtual Machine really amazed me. It was clean, simple concept yet the code verification rules were set in such a way, that it was always possible to compile it in most efficient way. The choice of instructions is well balanced and allows good CPU optimization.

So I started JAVA and fell in love with it.

And this is a place where I am now. Do micro-controller in assembly or eventually in C and then do PC side in JAVA, usually with some tiny pieces of C native code to get to system I/O resources.