Smartphone/Tablet Apps – Should they be better documented ?

It’s a sad fact that many of the Android and iOS apps that I’ve come across in my travels have been poorly documented and leave the novice user perplexed as to how they work….

I began to wonder why this might be the case quite soon after starting to use smartphones & tablets myself. Having authored quite a bit of software over the years (for pcs rather than mobiles), some of which was produced to support work projects and has been extensively used by professional colleagues, I had some prior knowledge of the coding process - and what goes into validating and documenting an app. This provided some insight into why developers might find it hard work to provide full instructions for their apps. It also provided some clues as to why early releases of some apps have a habit of crashing when used by the unsuspecting. I wanted to explore this a bit further, since these are both important issues to address for any app developers wanting to get their apps downloaded and used.

The Importance of Documentation

First, let’s consider why documentation is important.

Developers write their apps for a number of reasons – at the root of things is usually strong desire to generate code which does something clever and is interesting to others. This is often combined with a desire to generate an income stream. Whatever the initial motivation, I suspect most if not all app developers would like to see their apps downloaded, installed and used regularly by others. Many apps are written under contract for commercial purposes and actually help provide an income for their developers.

When it comes to the user experience, the first thing of note is that there are a lot of excellent apps already out there, many of which are free to download. This means that a new app appearing on one of the download platforms will have stiff competition for the attention of the user community. Anything that acts as a deterrent will reduce its competitiveness and therefore its uptake. And downloading isn’t by any means the end of the battle – to get ‘ratings’ and provide any sort of income / notoriety, the app needs to be easy to use from the start - and enjoyable in order to get good user-feedback and ‘likes’.

As a developer, it’s important to remember that your user will almost certainly have had no experience of your new app, so won’t know how to use it. If they are faced with a confusing array of indecipherable symbols or icons, no menu system and no help functionality, as some apps are, they will quickly give up on it. However well it's written, and whatever ‘smart’ functionality it may sport, you can be sure that the app will very quickly be consigned to their particular ‘uninstall bin of history’ if the user can’t work out how it functions within the first few minutes of starting to use it. Few will invest time and effort beyond that.

Given the vast amount of time and effort the average developer can spend compiling and testing an app, a little more effort of documenting it properly is well worthwhile, and can be worth its weight in gold. Unfortunately, once an app is complete and working, and has thus satisfied the developers initial urge to create, the same ‘drive’ will quickly induce a desire to move on to other things. Thus documentation may at best be seen as a 'chore' and at worst be completely ignored.

Now I’m not implying that all apps are poorly documented – far from it. There are some excellent examples of apps out there where a lot of time and trouble has gone into ensuring the user has a good experience from the start. Sadly, though, there are many apps that are obviously well-written and perform some amazing functions, but fall by the wayside because users can’t easily work out how to use them, and just ditch them immediately after downloading, moving quickly on to their competitors' offerings.

How should an app best be documented to attract the user – and keep them happy and engaged thereafter ?

First and foremost, it needs to have a built-in help function of some sort. At a bare minimum, a brief but succinct text description of who the app is intended for, what it does, and how its functionality might be useful to the user. 

A step-by-step startup guide for new users is a must – i.e. what to expect when you first run the app, how to begin using it,  and where to get help while you’re using it if you get stuck. This should preferably present itself as an option immediately after installation with an encouragement to read the contents before using the app to ensure they as users get the best experience.

I’d recommend the help package is actually written into the app’s code – a link to a separate web page is another alternative, but given the minuscule space taken up by plain text, it should be possible to integrate a reasonably comprehensive help package into an extra  megabyte or so of space within the .apk file. Remember that not everyone will have (or be able to afford !) instant access to mobile internet data ‘on-the hoof’ nowadays and so a stand-alone approach is the best wherever possible.

Who should write the User Guide ?

Contrary to what you might think, the app developer isn’t the best person to author an app’s help package and user guide, and is the worst person to actually test it. The reason is a simple one – having written the thing, he/she will be totally familiar with the vagaries and querks of how the app works, and will unconsciously allow for these when using / testing it. A novice user will of course have no such knowledge and may well get tangled up in relatively simple operations that would appear child’s play to the developer.

To avoid missing possible snags and ensure the whole thing is comprehensible to the novice, I’d recommend the developer generates a first draft of the help / info package, then hands it over to someone who isn’t familiar with the app, and asks them to run it sight unseen using the draft instructions. A critical report from the evaluator of any problems experienced while doing this, and any improvements needed, will then help the developer to refine the help package (and if necessary the app itself!) before ‘going live’ with it.

This last suggestion reminds me of the importance of validation in all things software-related. Before an app is released, not only should it have a critically-reviewed help package, as suggested above, but the app's functionality should always be ‘tested to destruction’. Again, the developer is probably the worst person to do this – rest assured that if your app contains bugs that you haven’t yet discovered (as almost all of them do!), someone out there will find them for you…and make you wonder how on earth you missed them.

I’m not suggesting developers need to go to the lengths regulatory authorities such as the FDA and MHRA demand for all software used in studies submitted to them for pharmaceutical product registration; there, everything used to generate any sort of study data has to be formally validated and strict change control applied to each new version of the software, firmware and hardware used thereafter. The same principle should apply, however, to mobile apps. Some form of independent testing exercise is always to be recommended for any new app before release and for each revised version of it released for use thereafter. If this practice were more widely adopted in the world of smartphone and tablet apps, it might actually help avoid excessive ‘tinkering’ with the apps and thus reduce the number of failed updates ‘unleashed’ on unsuspecting users.

If you think about it, all this makes good sense for the developer – if your app ‘falls flat on its face’ and crashes the first time a new user runs it, it will quickly be consigned to the recycle bin of history, and may well get you a bad reputation with the app stores to boot. A ‘tame’ reviewer / tester will be very useful here – you may need to ply them with plenty of drinks for their trouble, though !

Last but not least, the extra time and effort spent in documentation will improve your profile as a developer. Not only will you gain valuable insight into how to write apps with end-users in mind, but you’ll get a wider perspective of your app's applicability and user appeal from the review process. This will enhance your programming and documentation skills for future projects.

OS Version Compatibility

As someone who dislikes waste in any form, and is mindful of environmental concerns about the UK’s e-waste ‘mountain’, I have become increasingly appalled at big tech’s attitude towards planned obsolescence over recent months (see previous blog on this subject for more info.).

I’d like therefore to take this opportunity to add a ‘plea’ to app developers everywhere to think about downward compatibility with older OS versions when designing new apps.

Now I appreciate that a brand spanking new Android app, for example, which is designed for Android v 11++, and has all the bells and whistles going, probably isn’t ever going to be compatible with older tablets and phones running Android 4.x or earlier. For one thing the chip-sets in these devices just haven’t got the electronic ‘oomph’ to deal with the new coding functionality and processor speeds required.

What developers need to remember, though, is that there are an awful lot of these devices still in good working order out there. Many of them are already sadly languishing in drawers with flat batteries and destined for the skip simply because their users can't get anything out of Play Store or the Apple store, now that Google/Apple have withdrawn support for their particular OS version. In the ‘bad old days’ when concern for the environment was just a new ‘fad’ and there was plenty of consumer cash sloshing around, when faced with app incompatibility, users tended to scrap their phones / tablets as a matter of course and just upgrade in response.

However, as we all know from recent experience the world has changed….users are becoming more environmentally aware by the day, and given the extent and likely persistence of the current cost-of-living crisis, it’s unlikely that the average phone user will be able, or indeed willing to support the cost of upgrading annually, even if they have done in the past.

Even mid-range phone can cost several hundred pounds, and the likes of the iPhone variants run into the thousands and require a small mortgage to acquire nowadays (not so funny at 6%+ interest rates!). Thus, many will need to hang on to their 'old' technology for a lot longer, which from an environmental point of view is no bad thing. By failing to make their apps downward compatible, developers are effectively excluding a large potential market – not particularly good business strategy, to say the least.

So if you want to maximise your app's ‘coverage’ in this new more financially-challenged world of ours, try to make sure it’s compatible with as early an OS version as the functionality will allow – even if that means scaling this down a little. It will help the environment, and will be appreciated by a lot of users. 

It may well also improve your following stats…..

First published 30.6.23