Sandboxed Solutions and SharePoint Records Centres

When you attempt to deploy a sandboxed solution to a SharePoint Records centre from Visual Studio you will get:

Error 1 Error occurred in deployment step ‘Add Solution’: Value cannot be null.Parameter name: g

If you try using the PowerShell command Get-SPUserSolution the same thing will happen.

The root cause is that the Solution Gallery does not have a Solution Id filled in for the solution.

I have tested in SharePoint 2010 and SharePoint 2013 and the results are the same.

I’ll try and get clarification from Microsoft but this does have an impact on what you can do for hosted solutions, including Office 365, in customising the records centre.

Chiz

Sebastian

Writing the Documentation for a Design Up Front

Well this turns out to be far harder than you would think it is.

Once you put yourself in a user’s shoes things look very different.

I started the User Guide 1.1 for the next release of the Enhanced Records Management product and immediately realised that the vocabulary in version 1.0 is hopeless unless you already know both SharePoint and the architecture of the solution.  I started a glossary translating Records Management vocabulary into SharePoint Records Management vocabulary and this I realised was a dead-end in itself.  I used a bit of my misunderstanding of Stanislavski and imagined I was a Records Manager whose main concern was to care for my records.  I don’t know SharePoint and frankly I haven’t got time to learn it.  I do have a SharePoint Records centre though and I have to use it.  In my old friend Ed Texeria’s words:

What’s the least I need to know?

Not much it turns out.

• What policies have been set up to govern retention?
• How do I change the policies?
• What events do those policies depend on?
• Which records are dependent on which policies and hence which events?

Hold on even that’s thinking in a ‘data centric’ sort of manner.  Lets try again but this time thinking of it from arriving in the morning with a steaming mug of coffee.

• What records do I need to deal with today?
• What records do I really need to deal with today because they are overdue?
• Are there any records that I don’t have a policy for?
• How can I set up a policy for records that don’t have one?

Interesting I’d probably change the first two round now I think further.  It seems to me that getting those things right is what my job is all about.

I probably have some other responsibilities that occur on a less frequent basis and I may even have staff who can help me so once we have dealt with the critical matters what would the next most likely things to occur during the day?

• I’ve had a request about a topic how do I satisfy it?
• How do I find out what happened to the record the auditors are asking about?
• Have any of the projects closed or any one left us, as due to this event I need to start the clock running on all the relevant records?

Okay that’s probably enough to get going on for now.  What is interesting is that none of this cares about how I do it I could be using a paper based system and the questions would be the same.   Also looking at the questions it seems that the ‘keywords’ are:

• Record(s)
• Policy
• Overdue
• Find
• Audit
• Event

The Record(s) is interesting because I want to deal with records in groups to reduce the time it takes.  I know that the record management vocabulary for a group of records that will be handled simultaneously is a ‘part’ and that a ‘class’ is a records management term for a branch in a ‘file plan’ whilst a ‘part’ is a leaf and the only thing that can contain a ‘record’.  So adding these to my other keywords gives me a very small vocabulary to start with:

• Record
• Part
• Class
• File plan
• Policy
• Overdue
• Find
• Audit
• Event

I’m sure more will crop up later but that’s enough for now.

So in my introduction I want to define these terms so that as a Records Manager I know that this manual is speaking my language, not some techies.

Onwards!

Sebastian

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