Documentation Driven Design

Hello, World!

Things bounce around in your head for ages and you never get around to formalising them even though they are an obviously good idea.

• What is the biggest gripe users have with software?  How hard it is to use.
• What do developers hate doing?  Documenting the software.
• What is the most expensive thing about software development?  Making changes after the software is released.

I think these things are all related and stem from a single cause.  Optimism.

The Problem

Developers are rightly proud of the difficult work they do and being, on the whole, proactive people tend to assume the best.  I can write it in an afternoon, it’ll work nicely and everyone will love it because I’m so clever.  It will be simple, easy and obvious, in fact it’s really the only way that something like this could work.

Problem is that developers rarely understand what is actually needed.  If we look at a simple problem such as ‘draw a circle’ I can quickly come up with an algorithm that will do so I can probably even work out what the user will want to do to the circle, determine how big it is, what colour it is, maybe even squash it.  When users get hold of it though they use it to solve real world problems so they maybe also want to fill it with a colour or move it or even attach data to it.  Now imagine a real world problem like ‘take an order’.  How little do I know about that?  Actually if it’s for a HP Unix T-Series or similar a ridiculous amount, accident of personal history, but if it’s for a car or a bathroom?  In fact I know almost nothing.

So who does understand the problem?  The end-user obviously but as we love abstraction and indirection typically the developer is well insulated from them.  Direct contact is problematic in practice for a number of reasons.  End users and developers tend to be quite different in outlook and aspirations and they talk different languages.  So we provide a translator, traditionally a Business Analyst and a Project or Product Manager, maybe a Designer or UI Expert, Marketing may even get their heads in.  Recently I’ve noticed a resurgence in the number of Business Advocates who ‘interface’ between Technology and ‘The Business’.  Now we don’t necessarily want to bring the developer in direct, unfettered contact with the end-user but a chain of three or four people has one obvious result.  Chinese whispers.

Now lets talk about something no-one likes to talk about these days.  Continuity.  As an old boss of mine once said to a customer “If you want the team to stay together you have to give us more work, otherwise I disband them.”  It was a myth that with a bigger company you got continuity as in effect software houses rarely have long running teams but grow and shrink them to meet demand.  It is now a myth that development is so simple that you can replace one developer with another, all they need to do is read the code.  This may occasionally be true but it relies on the code actually being readable and having its intent clear with it.

Finally lets examine the cost of change.  No matter what mechanism you use for software development from waterfall to agile there is one thing that you can state which is that as the project continues change becomes more expensive.  We could argue about how expensive but that’s not important and agile methods due to their lighter ‘baggage’ tend not to escalate the cost as quickly, but they do escalate it.  Why?  Effectively because of the rule of unintended consequences once a system becomes sufficiently complex to do something interesting you are no longer holding all of it in your head, unless you are in your early twenties, and certainly unless you wrote it no other bugger is ever going to hold it all in their head.  This means that you need to check for unintended consequences and whilst agile is a great help here it does not eliminate it.

Whilst we are on the subject lets talk about the change we all try and ignore.  Developers ship working but unusable software.  They claim it is correct it does the job and technically it does but the user claims it doesn’t work or it’s too ‘clunky’ or ‘complex’ or ‘unintuitive’ or just ‘wrong’.  Impasse.  Tempers rise the developer has done what he thought he was asked to do and the user has been presented with a complete mess.  The real problem here is that they are both correct.  So a change is made but as the developer has already written scads of code the changes are now more difficult and complex than originally foreseen or the existing code has to be abandoned refactored at extra time and cost.  It’s not just developers who suffer from this I’ve had ‘specifications’ from design agencies over the years that I as a user just would never put up with.

A Solution

I started with three things and maybe if we look at all of them together we can come up with a solution.

If a user could get an idea of how the thing will work before the thing exists they might be able to see if it would suit them.  Not if it works but if it would ‘work for them’.  They might also be inspired to suggest how it could be improved.

If we could produce an inexpensive artifact that the user understood then we could reduce the chance of an ‘expensive’, and from the developer’s point of view arbitrary, change when the user actually sees it.

If the end documentation was mostly written before the code then when the going gets tough and time is of the essence we would at least have something and if we want to just change it ‘for the better’ we would have to change the documentation or the change will be obvious.

Similarly if the user in the meanwhile figures out a ‘better’ way they can’t change their mind without it being obvious.  Not that this matters but we can then have a discussion about why they want to do it and we can explain what is difficult about the new approach if anything.

Hold on though isn’t the end-user document then actually the closest we have to a ‘statement of requirements’?

Yes it is and although couched in business terms it’s also our architecture diagrams as well.

It will be huge, incomprehensible and a millstone around our necks.  Won’t it?

Not necessarily.

Years ago I toyed with a concept of ‘A Page About …’ documentation, that is documenting systems by writing no more than an single side of A4 about any one aspect of them.  This was on the grounds that anything that took more than a page to write up was basically too complex to be retained by the average reader.  Patronising yes but years later I find myself constantly having to stop the documentation I write just growing bigger and bigger whilst not saying anything more.

So without being as prescriptive as a page about there is only one thing left to do.

Try it out

I have a client who wants a feature added to some software I’ve written.  This software is embarrassingly badly documented but does run very nicely.

So over the next couple of weeks as I implement the feature I am going to try out this new Documentation Driven Design.

Stay tuned.

Sebastian

Unit Testing SharePoint 2013 with Visual Studio 2012

Hello Once More

Yes it is possible to do this and its easier now than in Visual Studio 2010.

If you own Ultimate then there are shims and mocks ready rolled but if you don’t you can use SharePoint itself.  This will make these Integration Tests rather than Unit Tests but having been using them for a day I’ve already caught three minor issues in under an hour.

1. Use Visual Studio to create your SharePoint project as normal.
2. Use Visual Studio to create a Test Project as normal.
3. Add a project reference from the Test Project to the SharePoint Project.
4. In the Test Project ensure that Test > Test Settings > Default Processor Architecture > X64 is selected in order to avoid this error:

Microsoft SharePoint is not supported in 32-bit process. Please verify that you are running in a 64-bit executable.

Then write your user tests as normal and off you go.

Cheers

Sebastian

How to reboot your Android device

Hello

This should be easy really and it is.

1. From your development machine connect via a USB cable.
2. Run the following command:

adb -s <serialnumber> reboot

So for my cheap and cheerful tablet it is:

adb -s 20080411 reboot

Cheers

Sebastian

Developers only tend to see what helps them do development

A quote from Gina Holden who has dealt with developers for longer than anyone should really have to.

It came up in discussion about what is agile programming, or rather what is Agile?

I pointed her to the original Agile Manifesto and her comment was:

Sounds great and practical apart from “Customer collaboration over contract negotiation” – that’s just stupid and naive.

We then had a little discussion about the difference between ‘over’ and ‘instead of’ and I pointed out that most developers treat the right hand side (or RHS as we techies like to call it) as BAD whilst the left hand side (or LHS) as GOOD and that this was not the point.  The aim is really LHS GOOD, RHS GREAT.

This then gave rise to the fantastic quote from Gina:

Developers only tend to see what helps them do development – not what the rest of the project is doing……

And this gave me pause.

I think of Agile as a thing in itself but really it’s just part of the development chain, scrub that, it’s part of the delivery chain, scrub that it’s a way of looking at the whole project.

Yes the whole project.  Not just definition, not just development, not just deployment.  It’s a way of looking at the entire lifecycle from cradle to grave, of an idea.  It could all be agile from having the idea to delivering the first version to sun setting the final version.

With this in mind and bearing in mind we have just started on an idea

Help people get places via public transport

maybe we should be doing it.

More to follow.

Cheers

Sebastian

Google Map View gives ClassNotFoundException

Good morning

I just added a MapActivity to our Transports of Delight Android application and now when I try and start the application on the emulator I get the following in the logs:

07-17 21:25:58.004: E/AndroidRuntime(665): java.lang.RuntimeException: Unable to instantiate activity ComponentInfo{uk.co.simpleinnovation.transports/uk.co.simpleinnovation.transports.MapViewActivity}: java.lang.ClassNotFoundException: uk.co.simpleinnovation.transports.MapViewActivity

After much headscratching it turned out to be NOT explicitly allowing the application to use the Google Maps library as follows:

<uses-library android:name=”com.google.android.maps” />

This resolves the problem nicely.

Cheers

Sebastian

Setting up an Android Development Environment

And so I needed yet another android development environment.

Why?

See this post.

So I used the latest guide on the Developer Tools Web Site at http://developer.android.com/sdk/installing/index.html.

Note that there is an issue though.  When you try to install the Android Developer Tools you get:

Cannot complete the install because one or more required items could not be found.
 Software being installed: Android Development Tools 20.0.0.v201206242043-391819 (com.android.ide.eclipse.adt.feature.group 20.0.0.v201206242043-391819)

To solve this you need to add some sites to the “Available Software Sites”.

Juno
http://download.eclipse.org/releases/juno
The Eclipse Project Updates
http://download.eclipse.org/eclipse/updates/4.2

Also after the installation you get the configuration screen automatically.

Then all you need to do is install subclipse.

http://subclipse.tigris.org/servlets/ProjectProcess

Or just add http://subclipse.tigris.org/update_1.8.x as a new software location.

Cheers

 

Sebastian

Deploying Development Releases to Real Android Real Devices

The very first version of Transports of Delight, a useful travel companion Android App, is ready to be deployed to our real Android devices for testing.

This is a very minimal featured release being used prototype our development, test and deploy processes.

So how did it go?

Not well at all.

Why?

Well it turns out Microsofts Hyper-V engine does not support USB devices.  This means the ADB (Android Development Bridge) cannot access the test machine to install the software.

So what are my options?

1. Copy the .adk files via:
   1. Copy from development machine workspace\<Project>\bin to a physical machine transfer share.
   2. Copy from the transfer share to a USB drive.
   3. Attach the USB drive to the target Android device.
   4. Copy from the USB drive /mnt/usbhost1 to the relevant area, e.g. a backup area.
   5. Restore the apk backup
2. Install the development environment on a physical machine.

So option 2 it is.

This is when the mantra Marcus and I have been chanting in SCRUM meetings for years now shows it’s true worth.

“Deploy Early, Deploy Often”.

Cheers

Sebastian

How to create an Android VM using Hyper-V

Hello, World

As we start to develop Android Apps we are determined to do it properly, that is to maintain a high quality.

One of the things that helps with quality is testing and with testing one of the things that helps is to be easily able to get back to a known position.

Virtual machines are a real boon to this so I have created and snapshotted an Android 4.0 (Ice Cream Sandwich) machine in Hyper-V.

How to do it is beautifully explained in the following blog:

http://blogs.blackmarble.co.uk/blogs/rhepworth/category/hyper-v.aspx

Cheers

Sebastian

Getting the Android Development Environment Working

I was setting up the development environment for the Android version of our new product when I get the following error:

Cannot complete the install because one or more required items could not be found.
  Software being installed: Android Development Tools 0.9.9.v201009221407-60953 (com.android.ide.eclipse.adt.feature.group 0.9.9.v201009221407-60953)
  Missing requirement: Android Development Tools 0.9.9.v201009221407-60953 (com.android.ide.eclipse.adt.feature.group 0.9.9.v201009221407-60953) requires 'org.eclipse.wst.sse.core 0.0.0' but it could not be found

It turns out you need some optional parts of  Eclipse.

So in Eclipse under Help > Install New Software make sure you reference the correct version of Eclipse as well as the ADT toolkit, i.e.: http://download.eclipse.org/releases/indigo.

The link that helped me was: http://stackoverflow.com/questions/4249695/adt-requires-org-eclipse-wst-sse-core-0-0-0-but-it-could-not-be-found

Good Luck

Sebastian