DocBook

Big documents like user manuals are really hard to write using Microsoft Word. DocBook is a well-established standard that makes writing big documents much easier.

I needed to write a handbook on system governance for our clients. It is a complicated document that we will need to maintain for many years as our consultancy work grows.

I have written documents like this using Microsoft Word, but I found a lot of things difficult:

• Using the output for more than just print. Word's HTML is not suitable for the web. If I want PDF output, I have to buy more tools.
• Splitting a long document into multiple files. This makes it easier to change the document and to create alternative versions. In the past I have had to create lots of little documents and put them together after they have been printed.
• Getting cross references, tables of contents and indexes to work reliably. These are OK on a single document, but too unwieldy on anything more complicated.
• Keeping the documents up to date with the latest version of Word. I have used five versions of Word in the past 15 years, each introducing new incompatibilities.

OpenOffice.org makes it easier to keep up with the latest versions and can produce PDF straight from the tool. But it can not easily address the other problems I found with managing long, complicated documents and producing different versions in multiple formats.

I searched for alternatives and found DocBook. DocBook is an open standard for documentation, originally developed over 15 years ago by the publishers O'Reilly and others. It is supported by many open source and commercial tools.

DocBook is designed for complicated documents like technical manuals. It lets you write your document as multiple files, and processes these into many different formats including PDF and HTML. It formats the document automatically based on its content. It manages tables of contents, cross references and indexes. It lets you tailor the formatting without altering the source.

DocBook takes a bit of getting used to. I had to manually mark up the documents, and it took me a while to configure the formatters to produce the output I wanted. Some of this might have been easier if I had been using established commercial tools rather than the latest open source products.

But the results are exactly what I wanted. I can produce good quality printed output, with comprehensive tables of contents, cross references and indexes. I can produce the document as PDF, or as multiple linked web pages. If I wanted to, I could create Windows Help files, or rich text format to use in Word.

The document is produced from many separate files, which I control using familiar source code management tools. I can reuse the document files in many ways, for example to create tailored documents for individual clients.

If you need to write and maintain complicated documentation, you will struggle with a word processor. I recommend DocBook as an effective and viable alternative.

© Copyright 2007 Minimal IT Ltd. See the Minimal IT website for the original newsletter and copyright information.

Drupal

What do Ozzy Osbourne and Tim Berners-Lee have in common? Whatever it is, it could be disrupting your IT department very soon.

Ozzy Osbourne and Tim Berners-Lee both use the Drupal content management system (CMS). We started looking at CMSs to support a new venture to publish karate resources on the web (Shotokan Unleashed). After looking at the alternatives, Drupal was the obvious choice:

• It is hugely popular, and supports major sites like MTV.
• It uses industry-standard products (Apache HTTP server, MySQL, PHP).
• It can run on Linux or Windows.
• It is 100% open source - there are no hidden license restrictions or costs.
• It has a very active open source community.

As somebody who has spent years building IT systems, I was astounded at what you get "out of the box" with Drupal. After a simple install and on-line configuration, Drupal starts up with user accounts, security, menus, searching, and content management functions. There are hundreds of free add-on modules you can use to build websites that do pretty much anything.

Drupal is an excellent product, but that is not what interests me most about it. I think products like Drupal will have a hugely disruptive impact on mainstream IT.

• They can replace a lot of what we traditionally think of as IT systems. All the tedious engineering, such as user accounts and security, is built in. A large part of traditional IT is data gathering, data display, navigation, authorisation, work flow, all of which are built-in. Drupal has a Content Construction Kit (CCK) to allow custom data to be added to pages. Drupal could be used to implement a large part of many IT systems.
• They are very quick and very cheap. I can implement a fully functional and usable web site in hours, using commodity hardware, free software, and no programming. In my old job, it would have taken longer and cost more just to organise the meeting to discuss who writes the project proposal.
• They put control back in the hands of the users. Everything is set up on-line from within the product. You do not need systems administrators and programmers to get started.

We have had collaborative tools, cheap tools and end-user tools for years, but not all combined like this. A lot of what we currently do in IT, at huge cost and time, could be done in virtually no time and no cost by the users themselves.

I am not being naive. I know there is a lot of complicated back-end IT that this does not replace. If information is much more flexible, there is an even greater need for analysis to understand and organise it well. Large-scale long-term IT needs professional IT management.

But we must not stick our heads in the sand. Powerful, simple, cheap, collaborative, web-based tools like Drupal change the rules. If you work in IT and you do not understand tools like this, you could be swept away.

If the Prince of Darkness and the Creator of the Web agree, we had all better take notice.

© Copyright 2007 Minimal IT Ltd. See the Minimal IT website for the original newsletter and copyright information.

Portable applications - the experiment

Portable applications free us from many of the restrictions of the personal computer. But are they practical?

Portable applications run directly from a storage device such as a USB flash drive. I started thinking about them when my laptop broke, and I had to reinstall and reconfigure all my applications on a new one, which included a move to Windows Vista. It made me realise how much we couple our PC's personality (programs, configuration and software) to the hardware. It would have been so much easier to just plug in some sort of device and start where I left off.

Of course there are lots of other solutions to recovering a PC environment, such as disk imaging, virtualization and roaming profiles. But I am interested in portable applications because they are simple, and do not need additional administration and expertise.

Portable applications are not new. I can remember running programs from floppy disks. A lot of software, particularly on the Mac, is packaged to be portable. But for the vast majority of us who use Windows with software installed on the hard disk, there are lots of things we could do more easily with portable applications:

• Recover from failed hardware.
• Shuttle work between the office and home.
• Borrow the PC of a colleague, friend or client.
• Set up a tailored environment for contractors, without buying them their own PC.
• Distribute demonstration software that does not need installation.
• Preserve environments with old versions, for testing.
• Free yourself from many operating system quirks and incompatibilities, and for example run on Vista as easy as XP.

I am going to try an experiment. I am going to try to recreate my entire PC environment (office applications and a variety of development tools) as portable applications which run under Windows Vista or XP, and validate that it works by routinely switching computers.

I have done some initial setup. I tried some U3 applications, but most of these do not run under Vista. I had much more success with PortableApps.com, which provides portable versions of most of the office applications I use. I have set up the Tomcat Java-based web server, the Cygwin Linux emulator, and the XAMPP package for Apache web server, PHP and MySQL.

But just getting it to work is the easy bit. I have to rethink backups, upgrades and security. I need to understand what has to be copied to the disk to make it run (some web applications run too slowly from a flash drive). I need to recreate file associations and shortcuts. I need to fix clashes between installed and portable versions of the same software. I need to work out what to do with software that really needs Windows features like registry entries. I need to test that the environment is truly portable.

I do not need a perfect solution. I just want to demonstrate that it is practical and safe to set up a portable version of a complicated PC environment, and then explore the advantages of this.

I will let you know how I get on.

© Copyright 2007 Minimal IT Ltd. See the Minimal IT website for the original newsletter and copyright information.

Long-lived systems: call to action

You can extend the life of your IT systems indefinitely, but you do have to DO SOMETHING about it.

Change your mindset. If you put in a system and think it will only last a few years, then it will. But if you expect your systems to last for ever, and manage that way, then they will.

Be clear about system boundaries. If you see IT as a sea of "stuff" - servers, networks, databases, components - you can never get a clear view that lets you manage effectively. Cut up your IT into clearly defined systems. Make sure each system has effective business and technical owners who can make clear decisions to keep the system going, and who stop the system being forgotten.

Minimise the impact of change by keeping each system separate, or decoupled, from all the rest. This makes it easy to keep each system up-to-date, and not get forced into quick fixes because of changes in other systems.

Pick technologies that will last. Pick the major vendors and big open source projects, and look at the track record for smooth upgrades. The most boring, long-established technologies are likely to be the longest lived. Today's hot topics could be gone tomorrow.

Be paranoid when you design systems. Assume everything in and around your system will change. Do not try to cheat the inevitable by designing systems to cope with any change that you can imagine, because a lot of change is simply unimaginable. Put your time into effective decoupling within and between systems, well-defined interfaces based on established standards, and simple conventional coding. You want a system that is easy to change, not one that could cope with change if only somebody could work out how.

Do not avoid making changes when you should. Do a complete job. Sloppy coding, out-of-date documentation and incomplete test packs are a terminal illness. Justify change by the massive cost of the alternative: rewriting the whole system.

Watch your back. Monitor your systems to make sure none are falling behind, so that you know what you need to do to keep your systems up-to-date. Put in a framework like system governance so that you know what is going on, and what needs to change.

None of this is hard. It is all just common sense. It saves much more money than it costs.

So why don't we do this? When we were young, we wanted to grow up, and be an adult as soon as we could. In the same way, the history of IT has been a dash for growth, to exploit the possibilities of IT as soon as possible. Now that we are grown up, our priorities change. We want to keep fit and healthy, and live a long and fruitful life. We need to do the same with our IT. We need to realise the dash for growth is over. We need to look after what we have now. We need to grow up.

© Copyright 2007 Minimal IT Ltd. See the Minimal IT website for the original newsletter and copyright information.

Long-lived systems: monitoring

If you do not monitor your systems, they will die.

Imagine you have the perfect system. It uses all the latest, viable technology. It is beautifully structured and thoroughly documented. It is decoupled from all other systems. Every time it is changed, the code is refactored to keep it clean, and the documentation updated.

Good though this would be, it is not enough. The system could die quickly.

Although everything within the system is being managed, you also have to look at the external forces on the system. How do you know your perfect system is not being undermined: by technology shifts, changes in the law, new business strategies, and so on. You might carry out change perfectly, but how do you know when and what to change?

And of course, most systems are far from perfect. You have had to make tactical technology decisions, the systems are not well structured and decoupled, and the documentation is skimpy and out-of-date. Everything gradually breaks down as the system grows older. When should you do something about it, and rework the system?

You should change the system as soon as change is needed. But how do you know? In the real world, how do you set priorities for your limited maintenance budget?

You need to find out when and where change is needed, and to prioritise spend. This should be based on what you are trying to achieve: your IT objectives. You can measure your IT against your objectives to find the gaps. This shows where gradual decline is becoming critical. You can change the measures to reflect changing priorities, such as new technologies and new business strategies. This shows the impact of external forces.

As well as showing you when and where to intervene, measurement directly encourages long-lived systems. Measurement makes you split your IT into separate measurable chunks, which makes it easier to manage. You can measure systems for the effectiveness of ownership, for decoupling, for technology viability, and for design. Measurement does not just say, "This needs fixing", but it can also say, "Do this and it won't need fixing again soon".

Measurement helps in many ways. It can make sure that you get outsourced systems back in a better shape than when you handed them over. It lets you manage cross-system topics, like security, to follow through on investments and enforce policy. With a little care, you can even use measurement to estimate the return on your maintenance spend. You can show how spending money today will stop you spending more tomorrow.

Measurement lets you start from where you are. Few systems are perfect, but they are not all dreadful. Measurement shows which systems are OK, which need significant rework, and which are so bad they need to be abandoned. If you want to get organised, measurement is where to start.

System governance provides the measurement and monitoring that you need. It shows you when and where you need to change your IT to keep it forever young.

© Copyright 2007 Minimal IT Ltd. See the Minimal IT website for the original newsletter and copyright information.