Making friendly interfaces

Sitting down with George Bina, we discussed the technical side of implementing human-friendly authoring interfaces, looking at examples from what Syncro Soft have done with <oXygen/> XML.

George Bina

George Bina

Partner, Syncro Soft

Twitter: @georgebina

Rick: Hi George. What have you been up to recently?

George: I’ve been to quite a few events recently, both in the US and in Europe. We’ve been doing customer and prospect demonstrations.

I’ve changed something about my presentations recently, and it slightly surprised me. My talks are usually very technical. I’m a technical guy. But I’ve started speaking a different language. I don’t talk so much about the technical part of what we’re doing; I focus on the business reasons. And there’s been a lot of feedback along the lines of “we understand you.” Indeed, one audience actually complained that it wasn’t technical enough.

Rick: People, you just can’t please ’em!

But generally, I agree. We need to be talking to people about what technology can do for them. They really don’t care how it works; they just want to know the benefits. We have to speak a language they understand.

George: It’s as though, in the last few months, I learned to communicate.

Rick: It’s all down to practice.

George: Really, this shows that you understand what your users need; when you can talk to them in their language.

Rick: As I quoted Willie Brandt in the book (p55): “If I am selling to you, I speak your language. If I am buying, dann müssen Sie Deutsch sprechen.”

George: Speaking of the book, I enjoyed reading it.

Rick: Thank you.

George: I liked that many of the things you brought up about making the tool usable for the people managing the content – not just those you publish to afterwards – we’ve already addressed to some extent.

Rick: Which ones have you dealt with?

George: Basically that you have to invest in a user interface that makes sense to the target audience; to those who use the tool. And modelling that interface using concepts those people understand.

In many cases, the logical content management paradigms don’t map one-to-one with the storage structures someone has decided to use. We see a key part of our role as providing a user-transparent translation between how people think about managing their content, and how we need to store it.

Rick: That sounds pretty simple, doesn’t it?

George: It came about as a result of adding cool technical tools to the product. We were able to add buttons and drop downs into the middle of the document. But we couldn’t explain the value of that functionality to our audience. We had to create examples of working interfaces that showed the business value of using these features. Then, we had examples that made sense to our audience. We weren’t telling them what they could do, we were showing them real benefits of the technology in action. They get to see what the functionality can do without thinking about it as a technical feature.

And as a bonus, these sample implementations made great developer references.

Rick: So, by focusing on implementing the technology in ways that would give real business value, you created reference implementations that we usable in the real world.

George: Exactly.

Rick: What have you done to make it easier for authors to manage their content? How have you managed to hide the structure?

George: There are two basic approaches to getting people to create structured content. The first is to give them a blank document. Let them do what they want. And then it’s our responsibility, manually, to convert it to the technical structure we need to use it.

Rick: Until someone wants to revise it…

George: The other option, the one we are trying to promote, is guided editing. We can use a simple XML format, or a simplified interface superimposed on the XML, and provide hints to the users directly within the document. If we expand this idea, we can still let people use tools they’re familiar with – a word processor, HTML, Markdown – but we integrate that interface with our content validation model. We have a real-time translation between the two. They are the same document. They are the same content, with the same logical structure. One of them might be the format we technically store the content in, but there is a reversible and repeatable mapping between them. If you make a change in one environment, it shows up immediately in the other. If you try to do something the structure doesn’t allow, we can guide you to correct it.

Rick: Have you got an example of this?

oXygen XML Language of Content Strategy inline actionsoXygen XML Language of Content Strategy editable referencesGeorge: Yes. I created an interface for managing a multi-contributor book, in the style of The Language of Content Strategy. You need a copy of Oxygen XML, and the editing framework that is available on GitHub.

Rick: That’s brilliant. You’ve got an environment that helps the author provide exactly the material that’s needed.

But the obvious question is: how long does it take? How much effort goes into creating an interface that makes the environment easier for the authors to use?

George: The Language of Content Strategy example took me about nine hours; say two days if you count all the revisions.

Rick: While I know some people would complain at even that amount of effort, it’s pretty obvious that it pays off almost instantly. Something similar done in a business environment would show a tangible return within a month, assuming the right bit of automation was done.

George: It’s a winning solution.

An XML document underlies all of this; the document becomes the entire user interface. And our definition of the XML document can include some fairly complex structure: repeatable sections, expandable elements, et cetera. We can also include how all of this translates to the users chosen authoring environment.

Rick: Okay, now you’re going to have to really impress me. I like what XML can do; that it’s a declarative language with syntax for not only the structure, but also actions. And I’m all in favour of real-time translation. But as you mentioned earlier, and I have come across several people who think this is the best authoring environment, how do you integrate this with something like Markdown? Aren’t these people just using Notepad?

George: Markdown needs a text editor. It doesn’t need Notepad.

We use XML. And as we said, XML can be very smart when it comes to presentation. It doesn’t have to display things with mark-up. We can provide – as part of the document – a translation between the XML structure and the associated Markdown. Markdown, after all, is just another way of serialising basic semantic structure.

Now, if we ditch Notepad, and use a text editor that’s really an XML authoring environment, but it can look just like Notepad, then we can detect the author’s interaction with the document structure and map that – on the fly – to the XML storage model we want to use. We can do this transparently.

And when you add Schematron rules on top of that, you can provide real-time in-line feedback on the content, as it is being written. If the description must be exactly one paragraph, and two are input, we can mark up that error, in the text editor, as the author is creating the content. And the feedback will be presented in business friendly language, appropriate to the authoring environment. It will explain that the description must be one paragraph, and why; it won’t talk about types of elements.

The content storage encoding that we use is irrelevant here. It’s only a serialisation, a representation of the semantics.

Rick: Right. I’m impressed.

George: We haven’t implemented this yet. We’re still working on it.

Rick: I’m still impress that you have a way of doing it.

It needs the right tools – tools that know how to interact with the XML and Schematron, tools which are really just an XML authoring environment that can present the document with embedded controls. But besides that, I think you’ve got a model that will realistically allow the easy creation of authoring interfaces that are specifically modelled to the mind sets of the people doing the work.

George: It gets better. We’re talking here about the source, the storage model, being XML. But it doesn’t have to be. Any form of structured serialisation will work. A real use case is the management of API documentation. The primary source, the definition of what we’re doing, is source code. This is written in a programming IDE (Integrated Development Environment). And because the source code is going to change, we can’t just copy it and maintain our documentation separately. The source code contains comments. The behaviour of functions, the parameters passed to them, the return value, and the output are all described in those comments.

When a programmer makes a change to the source code, they will also change those comments. A parameter may be added, or removed. So we can’t have our API documentation separate from the source code. We must use that primary environment to store everything.

But this is just serialisation. And it structured. IDEs have very strict semantic rules. Programming languages depend on them. So all we really need to do is provide a bridge between our API documentation authoring environment and the source code’s encoding.

Any document, whatever its structured format, can serve as the external source for our structured authoring. All we need is the serialisation mapping between the two. And, if we want to be nice to authors, the Schematron for the business rules with meaningful feedback messages.

Rick: This is brilliant: a toolset that –

  • Creates meaningful, business-focused content management interfaces,
  • Translates everything seamlessly – in real time – to structured storage,
  • Can serialise the content to any structured format, not just XML,
  • Includes business-focused rules and feedback, specific to the interface…

And you have an example of a fairly complex implementation – a clear guideline to the time investment needed to implement it, and the governance savings that results.