Everything looks like Bootstrap

Ever since I started using Bootstrap I can't help but notice that 3 of 4 technology websites I go to seem to be using it. Time to just incorporate it into HTML5?

Kids these days..

I recently started doing some development again on the side, and I can't tell you what a difference there is from the last time I coded. I'm using Ruby on Rails and developing is just a dream. Things like Bootstrap and JQuery make developing a functional and good-looking apps so easy.

Compared to the bad-old days of dodginess in the mid-90s it's so much easier. It's so much better than the early web MVC frameworks where I had to copy and paste the same 300 lines of java and XML code for every model; and let's not even mention the early days of Perl and PHP.

Nothing useful here, just wanted to share.

BABOK Requirement Types in Haiku

Business has a need
Stake holders require outcome
Function shows the way

(This may be one of the geekiest things I have ever done.)

Classic Software Engineering Essay

While I was doing some research for a requirements health check offering for work I came across this classic article that I remembered from an old battered copy of mythical man month called “No Silver Bullet”.


What it drove home to me was how little has changed in the 20 or so years since it was published. Good requirements are still central to the value IT delivers and we (as a society) still suck at them.

It’s an old article (1987) but still as valid as the day it was written. I especially love the way you can see the ideas that will come to be known as agile and cloud in it.

Article Text:http://www.cs.nott.ac.uk/~cah/G51ISS/Documents/NoSilverBullet.html

Lecture Notes on Article:http://www.cs.colorado.edu/~kena/classes/5828/s09/lectures/02-nosilverbullet.pdf

It's amazing how little the fundamental problems of building solutions have changed despite all the technical hype. Especially this quote “I believe the hard part of building software to be the specification, design, and testing of this conceptual construct, not the labor of representing it and testing the fidelity of the representation.”

Requirements are probably the hardest part of the solution development process, and the part that adds the most value. If technical design, project, and implementation are all fantastically then the result is that the solution is on budget and on time. But if the requirements and solution design are fantastic then it makes a real impact on people’s day to day lives, how well they do their job, and the effectiveness of their enterprise as a whole.

If you have an opportunity I recommend reading the article on the way home not in the office on your screen. It’s way too dense for that.

P.S. Some of the article is a touch dated. Time-Sharing is no longer a big change for example, and OO is not an innovation anymore; however Ada remains sadly under-used. Other bits are very prescient, such as a move towards iterative change driven development (e.g. agile), buy-vs-build, and even a touch of cloud.

Service/Security Levels

Here's an idea - next time you need to classify a service, product, or outcome based on quality - use a method that matches the service. Don't fall back on the old Gold/Silver/Bronze. Instead use a classification that gets across the trade-offs that are always implicit in classification.

For example when I'm doing security classification I like to use Titanium, Steel, Glass. This gets across that working with titanium is quite difficult, steel is easier, but if I want the service to be open and easily visible glass is a better choice.

It also gets away from the idea that more expensive is better.

GRACEful RAPID Decision Making

I love RACI matrices as a tool, but it always bothered me that governance wasn't covered and that the I for "Inform" was a little weak. Below are two alternatives, once if which I made up without meaning to, the other (far better one) focused on how to make operational decisions and changes.

I wanted to cover "Governance", and change Inform" to "Engage" which has the added bonus of being a meaningful word

• Govern: Oversight and stage-gate owner. May override decisions or act as impasse breaker.
• Responsible: Actually performs the activity and recommends preferred option.
• Accountable: Will be held responsible for the activity being performed, decision making authority
• Consulted: Opinions consulted in early decision stages, and kept aware of any outcomes
• Engaged: Made aware of decisions, issues and outcomes throughout project

Bain and Co also have a great model called RAPID that's better suited to operational decisons that setting up project governance:

• Recommend
  
  • Making a proposal on a key decision, gathering input, and providing data and analysis to make a sensible choice in a timely fashion
  • Consulting with input providers-hearing and incorporating their views, and winning their buy-in
• Agree
  
  • Negotiating a modified proposal with the recommender if they have concerns about the original proposal
  • Escalating unresolved issues to the decider if the "A" and "R" can't resolve differences
  • If necessary, exercising veto power over the recommendation

• Perform
  
  • Executing a decision once it's made
  • Seeing that the decision is implemented promptly and effectively
• Input
  
  • Providing relevant facts to the recommender that shed light on the proposal'sfeasibility and practical implications
• Decide
  
  • Serving as the single point of accountability
  • Bringing the decision to closure by resolving any impasse in the decision-making process
  • Committing the organization to implementing the decision

http://www.bain.com/publications/articles/who-has-d-how-clear-decision-roles-enhance-organizational-performance.aspx 

Easy to Use vs Hard to Misuse

It’s an awful thing to admit, but I think old mainframe green-screen applications are easier to use than slick web applications; where modern web apps have the advantage is that they are hard-to-misuse. “Easy to Use” is very different to “Hard to misuse”. They are two very different things with very different implications for system strategy, enterprise arch, and business requirements.

 

• Easy to Use: As a regular user or seasoned operator I want to be able to do things effortlessly with a minimum of interruption so that my workflow, thinking, or customer service is not interrupted.

• Hard to Mis-Use: As casual user or end customer I want it to be obvious to me how to accomplish normal tasks so that I can complete teh activity with a minimum of frustration and get on with my day.

 

I’d illustrate with calculators. I know I over-use the calculator similes; but I’m a geek and if you’re reading this chances are you are to.

 

Of my four favourite calculators in my house, I consider them all “easy to use” – but in really different ways:

 

• My HP12C financial calculator is simple for complicated calculations (Thanks to RPN) or financial calculation (Thanks to dedicated functions; but my wife can’t even use it to do simple arithmetic. It’s very easy to use – it’s just very easy to misuse it as well as normal people don’t think in Reverse Polish.
• My Blue HP is simple for my wife as she just types in the calculation, or for me when I’m learning new techniques as it displays everything on screen. It’s very hard to “misuse” this calculator as it feedbacks everything you’re doing to you, and uses the “standard” mental model of arithmetic.
• My Casio Calculator watch is simple for use on the go; despite the numbers being tiny and a lack of dedicated functions.

 

So the things I’d like to point out from this:

 

• Being hard to misuse generally comes from the systems metaphor matching to users mental model with the minimum of differences (My wife think of 1 + 1 = 2, as does my calculator.)
• Being hard to misuse is helped by copious user feedback – that is useful for keeping people calm that their operation is on track but may not be absolutely necessary (think confirmation screens, double entering passwords, etc)
• Being easy to use generally comes from dispensing with the feedback and cues and exposing only the information the user needs to know (Simple, powerful inputs. Command lines, etc)
• Being easy to use is enhanced by coming up with a different metaphor (Instead of “1 + 1 = 2” you get “1 push 1 +”) whose benefits are only obvious with prolonged usage.
• Easy to use is all about context. What makes my calculator watch easy is the tiny keys and screen which give portability – but in a desktop calculator this would be a major fault.

 

When you get it really right you come up with something that is both Easy to Use and Hard To Misuse. I think Google Mail is a great example. The core metaphor of “tags’ is simple and understandable, but can be very powerful once you work at it. It’s interface gives you a lot of feedback on what’s going on – but in a clear way that guides you through. It provides lots of keyboard shortcuts– whilst giving novice user cues.

Little Change In No Silver Bullet

While I was doing some offering re-read a  classic article that I remembered from my old battered copy of mythical man month called “No Silver Bullet”.

What it drove home to me was how absolutely central the work we do as BAs is to the value that IT delivers to an organisation, regardless of whether it’s always visible. It’s an old article (1987) but still as valid as the day it was written.

Article Text: http://www.cs.nott.ac.uk/~cah/G51ISS/Documents/NoSilverBullet.html

Lecture Notes on Article: http://www.cs.colorado.edu/~kena/classes/5828/s09/lectures/02-nosilverbullet.pdf

What struck me most was how little the fundamental problems of building solutions have really changed. Especially this quote “I believe the hard part of building software to be the specification, design, and testing of this conceptual construct, not the labor of representing it and testing the fidelity of the representation.”

What we do is probably the hardest part of the solution development process, and the part that adds the most value. If the PM, Arch, and implementers all do their job fantastically then the best result is that the solution is on budget and on time. If we do our job well then the system that we deliver can make a real impact on people’s day to day lives, how well they do their job, and the effectiveness of their enterprise as a whole.

  

P.S. Some of the article is a touch dated. Time-Sharing is no longer a big change for example, and OO is not an innovation anymore; However Ada remains sadly under-used. Other bits are very prescient, such as a move towards iterative change driven development (e.g. agile), buy-vs-build, and even a touch of cloud.

Setting Scope in Dimensions

Scope definition is the most contentious, and most useful, of a BAs tasks early in a project. It's a key part of mitigating the project's risks by promoting consensus on aims.

 

Personally I'm most happy when I can promote disagreements over scope within a project. Too often people are using the same language to say two different things, and do not realise there's been a disagreement until too late. A disagreement is proof that I've been successful in bringing this misunderstanding to the surface early, so it can be dealt with during initiation instead of implementation.

 

My favourite way of doing this is by describing scope in three chunks:

• In-Scope: My responsibilities as a project
• Out-Of-Scope: Things that will not be delivered or considered
• Dependent-Scope: Other people's responsibilities, that my project relies on

 

Out-Of-Scope is In-Mind

 

The best way do this is in the out-of-scope section. It's really the only scope section worth mentioning. Seeing a chunk of scope as explicitly out is much more confronting than it not being explicitly included. It's for wishful thinking to take over, and for stakeholders to see what they want "in-scope" if something related is also there, the out-of-scope section removes this false comfort.

 

In Your Scope is Out Of Mine

 

Dependencies on other projects should also go in the scope section. Theses are essentially things your project will not deliver, but is expecting others to do. Inviting the responsible parties from these projects to sign-off on your scope is an opportunity to get disagreements sorted early. Nothing focuses the mind like having to put pen-to-paper on a document that explicitly says what you are responsible for.

 

Multi-Dimensional

 

Explicitly structuring your scope statements around which 'dimension' of scope they refer to can make your scope clearer, encourage you to think about the projects in different ways, and make a point unavoidable by restating it from three or four different angles.

 

Each "dimension" of scope is a single narrow class of items that may be in or out of scope. I've listed a partial brain-dump of the dimensions you could use below.

• Problem: User issues to address or ignore
• Functional: User facing features that are included or excluded
• Non-Functional Requirements: All non-functional requirements can be part of scope, either as area we are targetting to improve, or where we make no promises. (Note that I'm a big fan of phrasing these as negative NFRs - things we can do without is what drives intelligent compromise.)
• System: Which technical systems we are responsible for, or will not change
• Interfaces: System interfaces or integrations that we take responsibility for changing, or normally rely on others for
• Activity: User activity or tasks considered, or ignored (Useful as part of a process when you highlight activities to automate or stay manual)
• Users/Customers: Which user bases are considered, and which excluded
• Organisational: Parts of the organisation whose issues and needs are in scope - very useful when deciding stakeholder and interview lists.
• Legislative: Which parts of law are to be complied with, or whose compliance is a main point of the program
• Deliverables: What documents, sing-offs, or artefacts are included
• Detail: How much details (Descriptive vs Prescriptive) will be included
• Supporting: Which activities or systems will be able to function based on our delvierables. This one's quite useful to say you will produce just-enough to support a particular activity or example (say, estimation) but not enough for another (say, full-build)

Logo for Android

I am really enjoying having Logo on my phone. Making that little turtle run around takes me back to first learning about variables and sub-routines on an Apple ][e. Good times.

 

This is almost definitely my geekiest post ever.

---

This message and any attachment is confidential and may be privileged or otherwise protected from disclosure. You should immediately delete the message if you are not the intended recipient. If you have received this email by mistake please delete it from your system; you should not copy the message or disclose its content to anyone.

This electronic communication may contain general financial product advice but should not be relied upon or construed as a recommendation of any financial product. The information has been prepared without taking into account your objectives, financial situation or needs. You should consider the Product Disclosure Statement relating to the financial product and consult your financial adviser before making a decision about whether to acquire, hold or dispose of a financial product.

For further details on the financial product please go to http://www.bt.com.au/general/rse.asp

Past performance is not a reliable indicator of future performance.

In Praise of Context Diagrams

The context diagram is probably the most neglected part of a BA’s bag of tricks. Nothing gives you the ability to collaborate with people so easily on a solution. A single slide with a good context diagram neatly summarises exactly what some functional component does, and who it serves. Whether it’s for a whole company, a system, or a software component, the context diagram applies just as well.

There’s lots of fancier ways of doing the same thing that give you a lot more information on context, aims, implementation, and scope – but none of them are so useful as tools to collaborate.

The beauty is that all you have to do is sit people down in a room, draw a circle in the centre of a white board and ask people who uses it. You then draw the users around in an arc in the top half of the board. Then ask what systems we rely on, draw those in an arc in the bottom half. Now ask what each user/system does with the solution and draw these requests and responses in as the arrows between external participants and the system.

It’s not fancy, there’s no certification course, but it can be the most useful meeting you have the whole project if you get it right.

Also, if you’re an external provider you can make these diagrams look very slick as you’re not restricted by a particular notation or layout. These give you a great way to advertise your competence, while displaying that you’ve understood the context.

Now – tricks!

• If you’re scope doesn’t cover the whole diagram you can use highlighted areas of the diagram to show in/out of scope, or multiple stages.
•  The MS Visio shapes for work flow diagrams and departments are a great source of icons for actors
• Minimise the number of systems you show, it should be mainly about users, systems are only their if they’re really significant.
• Maximum of four lines between any one user and the solution
• The “solution” in the centre of the diagram doesn’t have to be a system; it can be an organisational function, group, process, physical object, or anything really.
• If it helps – think of it as a top-level data-flow-diagram. But I don’t even know if they teach structured design in IT courses any more so that may not help you.
• Each arrow from users/systems to the solution could end up as one or more use cases or as a story grouping.
• Arrows going between users/systems to the solution can be verbs to capture actions, or nouns to capture data transfer. If you can stay consistent that’s nice, but it’s not %100 necessary.

P.S. In fact now I come to think of it most of what I learn in Structured System Design is generally under-used by the larger community. Perhaps because there’s no industry consortiums or consulting houses to push the method like there is for UML, BPMN, RUP, Agile, and all the other usual suspects?

Traceability and Business Rules in Word

A really good LinkedIn question from Adriana Beal on LinkedIn prompted me to write-up a neat little MS Word trick that can be useful for managing requirements traceability or business rules in MS Word.

It lets you create create consolidate of text scattered throughout your word document in a grouped list at the end using the same mechanisms as Tables of Contents, Indexes, and Tables of Figures.

This lets you do things like:

Reference business rules throughout your document and then include them all in

one appendix

Show a list of all Use Cases in your documents

Show a list of which Users, Screens, Systems, or Data Entities are involved in each Use Case

These are the basic steps:

• Create a custom paragraph style in world name it something like "Business Rule"
  
• Every time you reference business rule in your document put it on it's own line and apply this style (In our project we had a special section in each use case for the business rules)
  
• At the end of the document create a custom table of contents that lists all of the Business Rules in your document (Right click table, click edit field code, select field options, and you can then select which word styles show up in your table of contents). The resulting field code looks something like {TOC \f \n \h \z \t "Business Rule,2,Use Case,1"}
  

If you want a sample document that shows how to apply this style I've shared one from drop box: Sample File Download. The major downsides are:

• It's restricted to a single document
  
• You have to be a bit of a word nerd
  

Honestly it's a realy pain, and if you have an options you should use a wiki or a real requirements management tool. This is just a last ditch option to make requirements in word a little more practical.

Guirella Centre of Excellence

It's "reccomended best practice" these days to have a BA Centre of Excellence for any decent sized organisation, and most pieces of improving the performance of the BA function in an organisation being with getting senior management buy-in for starting one. This is fair enough.

But what if you can't?

I knocked togather a few powerpoint slides on low cost, cheap, fast ways to improve performance of the BA function in your organisation if you can't do anything formal. Essentially it boils down to:

• Encourage social contact amongst BAs
• Do information sharing at informal brown-bag lunches
• Have a good bookshelf on-hand
• Have conversations about basic theories, i.e. "What is a requreiment?"
• Use BABOK and IIBA to enhance the "professionalism" of being a BA

This all comes down to encouraging self-directed learning, and a team pride in the BA role.

Guerrilla BA CoE

View more presentations from harrislloydlevy.

Building Living Specifications

Producing new functional requirements for each project is evil and should be illegal, and punishable by death or working as a tester [1]. It is a basic cause of incoherent system, lack of holistic system thinking, and a lack of coherent documentation to support testing.

We've all had the experience of trying to understand the behaviour of a system and wading through reams of the original specification, change requests, and series of follow-on project specs, so why do we willing perpetrate this mess?

Probably a few main reasons:

1) The model of monolithic documents being prepared, signed-off, and developed against encourage this beahviour.
2) In the short-term it's the fastest way to get your individual project over the line
3) It's how we've been taught to do it
4) When we do decide to do something about it, we don't get angry that we're documenting badly, we get angry that we're documenting _at all_, and we implement some messy mix of agile and waterfall.
5) Wanting to have "all the information in one place" for decision makers (Which is a really valid point)

So what can be done about it? I'd generally propose a few changes that don't involve a massive change to current practices.

1) For new projects try to split out the project ephemera from the functional design that will be re-used.
2) Instead of having a singel plave for all project documentation, have a seperate place for storing project documetnation, system documentation, and process documentation. This reinforces that they should be treated seperately.
3) Gently ease into some business architechture questions, because if you're not using projects as the basic unit of information, you're going to need soemthing to replace it, and a system centric-organisation is a pretty poor substitiute.
4) Get some soom document/knowledge management systems. Shared directories will not work if you're moving towards lots of smaller documents. Consider Sharepoint as your first stop, and moving towards a Wiki and a Modelling tool in the long tem.

All of these mitigate against most of the objections I raised earlier, but they still don't give you the "single view" of the changes you're making for the project. Unfortunately there's no magic-bullet here. The more solution centric you make your documents, the less project centric they become.

Ideally you could mix-and-match content together into dynamic documents. But there's just no good tools for that, confluence is closest but really isn't there yet. There's a good summary of why up at http://confluence.atlassian.com/display/DISC/Using+Confluence+for+professional+documentation.

[1] Nothing against testers. It's just that most BAs hate working as testers.

Business vs Functional Requirements: I don't care.

Either I’m getting very lazy or I’ve reached a new point of sophistication in my BA practice because I really don’t care that much about the difference between business and functional requirements anymore. Maybe I’m just sick of the fact that it’s almost a point of pride for people to have their own definition.

Not to mention that fact that half of the time the “business” requirements aren’t from the business they’re from customers or regulators, and that “functional requirement” documents include non-functional things like service-levels and look and feel.

Half the time I don't even consciously differentiate between business and functional requirements. I just elicit a bunch of requirements, get the business to sign off to confirm that it looks like we have a shared understanding, and then specify a solution separately.

For me that's the big separation between classes of documents that BA produce

* Elicited Requirements: Documents conversations and consensus with stakeholders, embodies a shared understanding of situation, with the BA's role being mainly a drawing out from stakeholders.

Elicited requirements could be business, functional, stakeholder, objectives, KPIs, NFRs, show tunes, user stories, wire-frames, or just whatever works best for all stakeholders to communicate.

This is a big mess of "business" and "functional" requirements.

* Specified Solution: Documents a single concrete solution that addresses the situation embodied in the elicitation stage, with the BA's role being to design a solution based on the elicited requirements.

In this model I end up collecting mostly "functional" requirements.

I grant this represents my background working as a system integrator. In a fixed-price environment you really want to manage scope by keeping all that vague text in the elicited requirements separate from the model.

This has always worked well for me, with the following provisos:

* Traceability between elicited reqs and the eventual solution is key. You need to show where you took into account all the things your stakeholders said.

* You still need to understand the difference between business and functional requirements on some level so you know where you can implement something differently from the user request (And note it is such in your traceability)

* I’d never talk like this to someone just starting out as a BA. I think when you’re starting out you need to be much pretty dogmatic about the difference between stakeholders expressed needs, and their underlying objectives to avoid becoming an over-paid stenographer.

Customer Needs, not Functionallity

My Lamy ink pot is so well designed that every time I refill my cheapy $30 fountain pen I get a real sense of satisfaction, because everything just works.

I can feel that they've actually though about:

how a customer will use their product,

the acions they'll take immediatly before and afterwards, and

what place the product has in the customers life.

An inkpot is a fairly simple thing at it's heart. You just need ink in a well sealed container, lamy obvioulsy have great ink, and athe container closes tightly but it's a few little additions that make me willing to pay the %20 price premium over their competitors.



Lamy's have added two main feautres:

An integrated dispenser for plastic backed tissue paper around the base of the ink pot

A little reservoir in the bottom of the pot so that it's easy to get your pen or bladder all the way into the ink, even when you're down to the last of the ink.

So; from a BA point of view what have Lamy done that is so applicable to software design?

Firstly - they didn't think about themselves as providing a function (Ink, Email, holding customer records) instead they saw themselves as supporting an activity (Refilling a pen, communication, communicating with customers). By looking at a wider business-process context they were able to better integrate multiple functional components into something useful to the end user.

From a BA POV they took a wide process, and collapsed distincy activities together by providing a single interface that matches what the customer wanted to acheive. This is putting the customer's needs first, and the functionallity later.

Secondly - they looked at the whole lifecycle of usage. They introduced features that covered the whole product lifecycle, giving the customer unexpected bonuses towards the end of their product use; which usefully for a retail product is just when they're about to re-order.

But what's really great is that there's a synergy between the two, that little reservoir on the bottom is what paper dispenser clips to. There's also ongoing revenue from selling paper refills.

The only thing it's really missing is a way to easily open it when the ink has dried the list shut, maybe if base coudl be made square'ish you could get a grip more easily?

Requirements as risk mitigation

Really detailed use cases, and complete entity-relationship get a bad rap because they can be very complex to read, and are often not particularly good at describing the solution to end-users[1].

As a result they can get called a waste of time. We assume that requirements must be easily understood by business and IT stakeholders, and they seem to fail this rule - but most people persist with them out of a sort of gut-feel that they're useful despite being confusing to most users; and they're right to.

These sort of requirements mitigates your risk of internal incoherence, unwritten assumptions, and unexplored options. They may not be immediately readable by end-users but they ensure that the author has done a structured analysis of all the possibilities.

For example I had a project go wrong once because we assumed that each purchase order resulted in a single invoice, (e.g. a 1 to 1 relationship) when the reality was more complex (many to many). If a detailed ER diagram had been constructed the author would have raised this as explicit assumption. Similarly detailed use cases with very formal treatment of alternate paths are great at driving out odd little edge conditions.

Sometimes we produce requirements not to describe it to others, but to make sure we're across all the detail ourselves. This isn't the sort of work that gets users excited, but it does guard against something going wrong down the track.

[1] I've got some other posts about how to mitigate this, but that's another discussion

Three Types of Requirements

There are really only three methods for describing requirements in the whole world, these are:

* Imperative: "The system shall....."
* Prescriptive: "X = Y * 5. If X then Y. Use Cases, ER Diagrams, etc".
* Narrative: Bob hits X, Y happens, then Z. This is because A is true. If B were true we would do this.

Imperative is how everyone starts of doing requirements in their first job. Those long lists of "requirements" that make everyone's lives so miserable. IMHO you should never use these for anything but the simplest project.

Prescriptive is the model we move to after we've been hurt by scope creep a few times. We'll just lock everything down in a detailed unambiguous model that is 300 pages of impenetrable UML, and then we'll be OK. We won't have capture what the user actually wants, but at least we'll have documented it unambiguously.

Narrative is where we realise that our systems are only part of larger stories, and need to be seen in that context and we make the customer the centre of our design by giving them the starring role in the story. User Stories, or well-written use cases are good examples here.

This distinction has nothing to do with functional vs. business requirements. It's a seperate dimention about how we document requriements. The type of requirement is a compeltly seperate discussion.

Discreditting by Diagram

When you are putting together a before and after diagram you want them to be as clean, and as similar to each other as possible. This means that the effect of any changes is clear, and unaffected areas are obvious.

Sometimes though you just want to make the diagram as complicated and ugly looking as possible to get a point across or make a sale. You can't make it look like it's just a bad diagram - you have to give the impression that the author has really tried to make it comprehensible it's just that the underlying idea is bad.

The classic use of this is the IT department trying to get money to do a systems consolidation or re-engineering. The architecture team will dutifully come up with the ugliest diagram of spaghetti known to man, that will get presented as proof of how bad things really are.

Turns out politicians know this trick too; as shown below:



This diagram published by the Republicans on the Joint economic Committee “explaining” Obamacare is a classic of the genre. Undoubtedly high-price (and worth it) consultants have been consulted to make this look so complicated.

High res version here

It has all the classic tools to over complicate something:

Mixing Domains: This shows organisation structure, regulation, stakeholders, responsibilities, impact, legislation, and everything else all on the one page. This lets you put hundreds on boxes on the page

Lots of Boxes: Goes without saying - put as much as you can in there. Go crazy.

Complicated Legend: By having so many domains you get to put an overly complex legend on the bottom that shows all the different sorts of things. This requires lots of different shapes and colour coding. Which leads me to:

Colour: Use at least 7 or 8 different colours. This makes it hard to concentrate on text, and as a bonus you can have them all as similar shades so that when you print it in black and white you can’t tell the difference.

Lot of lines: All blank space should have lots of lines running through it. This way you add a lot of visual complexity, but it’s so hard to see what’s connected to what that you don’t add any content.

Acronyms: Put tons of Acronyms in that way no one can understand it without a glossary, and once you put in a glossary that’s another box of dense text to add to the complexity.

Tiny-Text: Throwing in some boxes with minuscule text give the impression that there’s even more complexity going on under the surface.

Miss the point: Put a crucial stakeholder or system in some out of the way corner, and then put something ridiculous in the centre.


Note: For the purposes of this article I don't particularly care about whether Obamacare is overly complicated or not, a good thing or not, it's just an interesting look at how the diagram designed can push messages.

We must hate trees a lot..

Why must every document I see start with at least 3 pages that are completely useless? Most of them manage at least 6, and I've seen up to 20.

Sometimes I just want to take these docs, scroll through until I find the first statement someone could reasonably disagree with, and just delete everything before this point. I don’t think anyone would miss it except for some putz who will insist it all the goes back in on the ground that it's "standard".

This useless filler generally consists of:

Title page. Generally containing no more content than is available in the document headers and footers anyway.

Distribution and sign-off page. This never contains any record of actual sign-off, the distribution lists is always out of date. Old emails will always be used to substantiate the real distribution in any case.

Version history. This is either so terse it’s useless, or so involved it takes three pages. It is never used by anyone; again the email trail is used as the de-facto history. Maybe if you document control system supports version that could be used.

Glossary and Abbreviation. A list of items that are either so obvious that all reader’s will understand and know them already, Acronyms so obscure that even spelling them out helps no one, or items explained in-depth inside the document anyway. No one will ever read or use this.

Document Purpose/Audience/etc. A whole bunch of explanation about what the document is meant to do and for whom. Arguably defensible for a “one-off” type of document; but for a standard template that you use again and again does the audience really need reminding that the purpose of a business case is to secure funding? It’s either things readers already know, or if they don’t know it they need more education than you can fit into the document intro.

Project scope/benefits/overview/context/etc. A whole bunch of generic description of the project that’s repeated (in slightly different wording) in every single document. In the best case scenario readers will just skip this; in the worst it will be different between documents causing confusion.

What’s the end result? 40 page documents where content that really matters doesn’t start until page 10. I’ve personally produced mounds of documents that are over %75 filler. This increases the cost of producing documentation, slows down review, and damages document readability. You can see why the whole idea of documenting an IT project is under attack.

What’s really galling is that this document bloat doesn’t come from business customers demanding more – the pressure is from inside the IT. Look at a memo, or a board paper. You’re lucky if there are more than a few centimetres of document meta-information at the top. A paper going to the board to recommend a few million dollars of spend fits on a single A4 sheet; but the smallest IT document we manage to make as long as war and peace, but with as much content as a limerick.

Solutions?

Manage meta-info (versions, approvals, distributions, etc) in the same system that manages your documents. If your system can’t support that and you really think you need it (unlikely) then at least move it into an appendix.

Remove purely aesthetic cover pages, unless you’re writing a book it’s just getting in the way.

Centralise repeated information in a living document. The project scope and overview document should be the only place that summarises repeated general project information. Put all the effort of re-drafting, re-reviewing, and re-writing the same content in every document into keeping it up to date instead. If you really have to reference it at the start of the document, if you really, really have to then copy and paste it with a explicit statement about where it was copied from.

Do what I said at the start of this post. Start at the top of the document, scroll down until you find the first statement someone could reasonably disagree with, and just delete everything before this point.