There are five basic rules you need to follow. Use these and you’ll usually communicate your intricate idea easily:

1. assume no prior knowledge
2. don’t patronise
3. entertain with analogies
4. distil, condense
5. test

You have to assume no prior knowledge of the subject you’re discussing. This doesn’t mean you have to spend hours elaborating the basics. Most complex concepts can be communicated using simple analogies to everyday things in the real world.

There’s a very delicate line between patronising your audience with explanations that are pitched too simply and diving too quickly into complexities that some won’t understand. Too complex too soon and you’ve lost them. No one wants to communicate with an audience and lose half of them along the way.

Using analogies, especially novel ones, allows you to explain to those who don’t understand the basics whilst still entertaining those that do. King Solomon was supposedly the wisest man in the ancient world. That’s because he knew every fable and parable back to front. So, faced with any complex conundrum put to him by his subjects, he could call up an entertaining story to put forwards his point of view.

It’s always better to keep your initial descriptions simple and allow complex technicalities to come out through questioning. If your audience thinks there’s something missing or would like to delve into intricacies, they will ask.

When you’ve drawn up your explanation, make sure you test it on two very different people: Find someone who knows your subject area reasonably well and someone who has little idea of it. Listen to their feedback, particularly the person with little expertise.

Martin Hawksey at JISC RSC Scotland North & East has done a very good job of this with his Make PDF Newspaper plugin. It uses the fivefilters pdf newspaper facility which itself centres on the Simple Pie RSS management toolkit. There aren’t too many options available but if you’re prepared to accept limitations in layout, the tool is a remarkably easy way to generate a good looking pdf version of an RSS feed.

We’ve been working a little with the plugin to get the output we want. The structure of the site we have pdf newspaper running on is fairly straightforward – posts appear as departmental news items and a bunch of static pages serve guidelines and a simple document repository.

We wanted a few of these static pages appearing in the newsletter which presented a conundrum as WordPress RSS feeds only deliver the posts side of the CMS, leaving the pages out completely. However, the RSS Includes Pages plugin alters this behaviour. It’s perfect for our purposes. All we need to do is to temporarily invoke it whilst preparing the newspaper. To get the right pages appearing, all we have to do is alter the publication dates so they fit into just the right place in the RSS feed.

One problem I encountered is a memory limit when making pdfs more than a few pages long. To resolve this, add a line like:

ini_set("memory_limit","120M");

to the beginning of tcpdf_config.php in the pdf newspaper plugin package.

The Firebug REST Client

In the example above you can see the URL, http://epsilon.nuhrise.org/alfresco/service/cmis/i/2c62291d-2e9f-4ac3-83a1-157406ffb2aa/children and the verbose response. In this case the response describes files in the Company Home space.

In the next article we’ll describe the web services our application Documas uses to view, upload and download files from Alfresco and we’ll also cover assigning and accepting/rejecting workflow tasks on documents from our external application.

The semantic web (sometimes called Web 3.0) is a generic term for a whole range of approaches that are looking to deal with the overwhelming mass of unstructured data the web is generating. Soon, techniques like Google’s search algorithms won’t be able to keep up with the trillions of web pages being generated. There needs to be a better way of understanding what web pages mean so that we can organise the valuable information they contain. It’s part of a move towards building clever systems that can reason.

If you’ve got 15 mins, Kate Ray has put together this compelling and instructive video about the semantic web, interviewing world wide web inventor Tim Berners-Lee amongst others along the way. There’s something of the Horizon about it; in the sense that it’s refreshing when difficult scientific concepts are coherently, simply and entertainingly described through video.

It’s part of a move towards building clever systems that can reason.

We’re using but a tiny part of the work on semantics for our own ends. We want to analyse a mass of web content, reasoning that if this can be done objectively and comprehensively by machine then it is probably better than anything we can do as humans. At least once you go beyond a handful of web pages; understanding the entirety of a few hundred pages can be a pretty tough job, unless you’ve got some clever tools to hand.

In the next few posts, I’ll describe how we used AlchemyAPI to do it. The tool enabled us to pull out context in terms of entities like people and keywords, places and subject matter. It helped us organise and rank all these things so we knew at a glance where each organisation’s focus was and how they were portraying this to the world at large.

Documas centres around a database model called Study. Studies are typically clinical trials that have dozens of properties reflecting their type and their progress. People such as administrators, lawyers, pharmacologists, nurses, researchers and clinicians act on these studies to progress them through a highly regulated approval process.

We chose to use Ruby on Rails for the CRUD part of Documas because, to paraphrase Bob the Builder, it’s the right tool for the job.

Much of the process is encapsulated in documents held in Alfresco, but equally a lot of the information is held in a normal database.

We chose to use Ruby on Rails for the CRUD part of Documas because, to paraphrase Bob the Builder, it’s the right tool for the job. Rails has easy ways to handle authentication (who), authorisation (what are they allowed to do), grids full of data, editing, validating and graphing. Above all, Rails is focused on the CRUD operations.

Rails also provides a http client to request ‘resources’, for instance documents, user accounts and workflow tasks from RESTful servers, like Alfresco.

If I’ve been a bit negative about the web front end of Alfresco, I’m pleased to concede that they more than make up for that with the way they open up the internal document engine to external applications using a RESTful interface.

REST is a set of ideas that promise to simplify communication between applications. 

If you have not come across REST before, there is an entertaining description here.

Conventionally applications use something like Remote Procedure Calls to call on each other for services, but every single call tends to have different parameters and return values making it hard to generalise and fiddly to use. In REST, the interesting parts of an application are available as ‘resources’.  Alfresco offers resources such as spaces (folders), files, people, tasks etc. Each resource can only do a strictly limited number of things, it can be created, deleted, changed or just read.  That’s it.  (The technical success of the World Wide Web can be largely attributed to REST, the resources are things with URLs, pages, pictures, tables of data, music etc. The operations in HTTP are PUT, POST and DELETE).

The designers of Alfresco have opened up the monolithic Java jungle inside Alfresco to expose the important resources. They have even documented it, a full list of approximately 370 Web Scripts (REST services) available from our Alfresco server is available at http://epsilon.nuhrise.org/alfresco/service/index, but you need to log in with the admin password!

In my opinion Alfresco also clutters the REST API with methods that return GUI elements, strictly speaking this is not REST because the resources are embelished with javascript for the user interface. The Forms Service in v3.4 is an example.

Inside Alfresco, the units of code that answer RESTful calls are called Web Scripts. They are written in Java and/or Javascript. The use of Javascript on the server side is clever because more people understand Javascript, and changes can be deployed with just a refresh of the web scripts rather than compiling and deploying Java class files. Otherwise one would have to maintain a Java build environment for the Web Scripts and employ at least half of somebody’s time just to develop and maintain the Java Web Scripts.

We’ve built a web application, Documas, on the solid foundation of the Alfresco Document Management system.   In this article we’ll explain why and how we did it.

Using Alfresco from another web application

Alfresco is a solid platform for managing documents and the events that happen to them during their lifecycle, but the ‘Web Client’ user interface is not suitable for most purposes because it was built by people like me, programmers, instead of by normal people. (The Web Client is also called Alfresco Explorer). As an example of the problems, try deleting ten files quickly.  There is no way to do a bulk operation and remove all ten in one go.

Alfresco Explorer

The Web Client is written in Java using a technology called Java Server Faces which in my opinion values gratuitous complexity over getting the job done.   (I think the adoption of JSF was the very reason the Web Client had proved to be hard to use, so much attention went into the JSF that little resource was left for usability testing).

Alfresco have addressed this problem by developing the ‘Share’ front end, a very Web 2.0, responsive and popular alternative to the clunky Web Client. But the Share web application is very closely tied to Alfresco and the kinds of document operations that Alfresco does. Our application needs to do those things, but also something called CRUD. Share, being AJAX, Javascript and REST based, is a sound choice for pure document management uses of Alfresco, but for our application we needed a little bit more. Over the next few articles I’ll explain how we went about it.

First remove the old first page:

pdftk OurDocument.pdf cat 2-end output OurDocumentMinusFirst.pdf

then combine the new first page with the remaining document:

pdftk NewFirst.pdf OurDocumentMinusFirst.pdf cat output NewOurDocument.pdf

Very simple indeed, but pdftk can do a whole lot more:

• Merge PDF Documents
• Split PDF Pages into a New Document
• Rotate PDF Pages or Documents
• Decrypt Input as Necessary (Password Required)
• Encrypt Output as Desired
• Fill PDF Forms with FDF Data or XFDF Data and/or Flatten Forms
• Apply a Background Watermark or a Foreground Stamp
• Report on PDF Metrics such as Metadata, Bookmarks, and Page Labels
• Update PDF Metadata
• Attach Files to PDF Pages or the PDF Document
• Unpack PDF Attachments
• Burst a PDF Document into Single Pages
• Uncompress and Re-Compress Page Streams
• Repair Corrupted PDF

The help manual that comes with the package gives a fairly comprehensive guide to options together with examples. Simply type
pdftk --help

Otherwise, there are plenty of guides available, like this one from segfault.

We’ve just been updating the design of one of our client’s sites and, as ever, fonts are a focus. Earlier this year, Google released a set of beautiful typefaces for use in web environments. It’s a simple matter of calling the font library from Google via a stylesheet header. Unless your choice includes Droid Bold.

Even easier, if you are using WordPress as a CMS, there are plugins available to implement the Google font API without much fuss. This approach gets you going very quickly and it’s very handy for look-and-see building.

But for a production environment, I don’t like the mess it begins to create of your stylesheet set. The plugin simply adds your styles to each page’s header which isn’t very elegant. We’ll soon be looking to incorporate the relevant css within the stylesheets proper rather than layering plugins on top.

The older design focused on Arial

Our implementation in question is for Nottingham University Hospitals Trust R&D. Here, the site is run using WordPress using an old but very solid theme called The Morning After. The theme itself has long since been taken over and incorporated into a commercial supplier’s portfolio. We’ve kept with the original theme and have slowly updated it to suit our needs over time.

The redesign involved some font size changes and text colour modifications along with the big shifts which were to Google’s Droid fonts. These look beautiful and there’s a large family to pick from, including a serif set. Whilst Droid fully modernises the look compared to the previous Arial, we recoloured and resized front page headlines to match those at the BBC website. This helps deliver a familiar user experience. We also softened the body text to a mid to dark grey which makes reading less tiring on the eye and allows us to use darker greys for block quotes and other text emphasis.

There are some tweaks to come, especially amongst the internal pages but for now we’ve achieved a fresh contemporary look with relative ease… except for an evil little bug. If your chosen font is Droid Bold. Of course our chosen font is none other. For some undetermined reason, many browsers except Google’s own Chrome are not calling the font properly. There’s a work around suggested by Alexandre Paquette over at Google Code

I found a way to fix this issue. By saving a local copy of the .css generated by de webfont directory, you can change the web font name defined in your css. for example, you can change “Droid Sans” for “Droid Sans Web”.

Bear in mind this will only happen if you make the local version that Alexandre mentions a priority; ie it has to be called before Droid Sans:

Put this in your stylesheet:

@font-face {
font-family: 'Droid Sans Web';
font-style: normal;
font-weight: normal;
src: local('Droid Sans Web'), url('http://themes.googleusercontent.com/font?kit=rS9BT6-asrfjpkcV3DXf__esZW2xOQ-xsNqO47m55DA') format('truetype');
}
@font-face {
font-family: 'Droid Sans Web';
font-style: normal;
font-weight: bold;
src: local('Droid Sans Web'), url('http://themes.googleusercontent.com/font?kit=EFpQQyG9GqCrobXxL-KRMQJKKGfqHaYFsRG-T3ceEVo') format('truetype');
}

Then decide where it’s going to operate like this:

h1{
font-family: 'Droid Sans Web', 'Droid Sans', sans-serif;
}

Ta-da – all your browsers will now show Droid Sand Bold almost properly. Almost? You’ll find that the strong tag doesn’t work consistently, leaving such things resolutely not bold for some browsers.

I haven’t noticed any overhead in making this external call but to be sure you should have alternative fonts specified, or at least specify a default sans-serif or serif as above; just in case there’s a connection problem.

An alternative is to host the fonts yourself. Defeats the object of using the Google API, but this is what you do:

1. Go to Font Squirrel’s Droid Sans section
2. Download the @font-face Kit. Make sure you check off each format so that all browsers are catered for
3. Upload the font kit to your own website so that they are then served locally rather than directly from Google

So, a spoiler workaround to an otherwise tidy idea. Judging by the bug report at Google Code, this problem with Droid Bold has been hanging around since the early summer and shows no sign of being fixed yet.

Herding cats is now a ubiquitous phrase that has come into management-speak to describe tasks that are tricky because things are changing and uncontrollable. Its recent popularity can be traced back to just a decade ago, during the peak of the dot com boom. It was used as the theme for an award winning commercial by ad agency Fallon for information management leaders EDS (now subsumed into HP), aired during the centre break of the annual Super Bowl baseball game.

Amongst the most expensive advertising slots in the world, this event regularly attracts an inordinate amount of effort from ad agencies and their clients. Little known outside the US and ad agency circles, viewers across the Atlantic will often find more entertainment during this ad break than the baseball game itself.

Although the tipping point for the phrase’s popularity was this IT services ad, its real origin was an obscure human resources reference book published a few years before, at the end of 1997. Warren Bennis‘s Managing People is Like Herding Cats is a book about leadership in management. Bennis was a pioneer of Leadership Studies in business and according to management guru Tom Peters:

“His work at MIT in the 1960s on group behavior foreshadowed, and helped bring about, today’s headlong plunge into less hierarchical, more democratic and adaptive institutions, private and public.”

The Financial Times named his classic book Leaders: Strategies for Taking Charge one of the top 50 books of all time. He believes there are six key qualities in becoming a successful leader:

1. Integrity
2. Dedication
3. Magnanimity
4. Humility
5. Openness
6. Creativity

And maybe the ability to herd cats.

And where did Bennis get the phrase from? A very likely candidate is science fiction writer, Poul Anderson. His post apocalyptic novel Orion Shall Rise dates from 1983.