# FreeGuide Design Document

This is a collection of thoughts about FreeGuide's design. Contributions, disagreements and comments are welcome.

## Target Audience

A TV guide is a very simple thing. In fact, my main reason for writing this application is that TV listings magazines are far, far too complicated for their purposes. This is brought about partly by the number of adverts and inane articles they contain, and partly because they try to list all the programmes everyone wants to see. FreeGuide attacks this problem on three fronts. First, it only shows the channels you ask for, second, it highlights programmes you are likely to want to watch, and third, it lets you produce a guide containing only relevant information.

So I want FreeGuide to be a simple thing to use. That means that any advanced configuration and so on should be in a place where the average user won't find it.

## Example Users

### Newbie

My Mum has got the hang of Outlook Express, and uses MS Word slightly tentatively. She should find it simple to use FreeGuide. Why not, it's hardly rocket science, is it?

### Hacker

FreeGuide is listed on Sourceforge, and therefore is likely to get a lot of its initial audience from people who really know what they're doing. They should be able to do advanced things like grab listings from a different web site, and search programmes powerfully using clever techniques. However, these abilities should sail past the basic user without being noticed. Otherwise we disguise the fundamental fact that listing TV programmes is simple.

It's worth noting that the hacker who just wants to get the TV listings quickly without learning anything will appreciate simplicity just as much as the newbie.

## Tasks

In order of frequency of use.

### Viewing listings

The primary use of FreeGuide is expected to be to look at what's on today, and print off a customised guide. It should also be easy to have a look at what's on tomorrow, and the rest of the week.

### Downloading listings

Every week or so the user will need to download new listings, by connecting to the Internet. This should be almost completely non-interactive, without taking away the user's freedom.

### Downloading channels

The user will probably only do this once, but it will be the first thing they ever have to do with FreeGuide, so it must be easy, friendly and non-interactive, again not taking away the user's freedom, particularly because they have to connect to the Internet before they begin.

Of course, the user will encounter these tasks in this order: downloading channels, downloading listings, then viewing listings.

## Progress so far

### 0.8

Again a step forward since FreeGuide is now installed using the normal installation mechanism for each platform, which means users don't need to learn a new way of installing just to use FreeGuide.

### 0.7

This release sees a large step forward with the addition of a GUI for grabber configuration, which means users don't have to open a DOS or Cmd window to install the program. This opens it up to a massive potential user base who would have been scared off before.

This release and the preceeding 0.6.x ones are beginning to see FreeGuide maturing, as useful features and bugfixes are being picked off one by one, gradually improving the consistency and ease of use of the interface.

### 0.6

Still missing GUI grabber configuration, but some nice features added - a heart to make clear exactly which programmes are favourites, and an added entry to the channel sets dropdown that lets you edit the channel sets from there (this should help people understand what this dropdown is for). Other nice stuff: progress bar and picture on the Please Wait screen, and progress bar on the downloader.

### 0.5

The major change here is that lots of new grabbers (for different countries) are supported, which is not totally UI-related, but nice nonetheless. UI changes in the form of a dynamically-updated list of available dates slightly enhance the user experience, and better handling of missing data makes things make a little more sense. The biggest missing element is a GUI for doing the configuration of the grabber.

### 0.4.3

Minor tweaks including remembering where you left the window last time you were using it, which can really improve the user experience, actually.

### 0.4.2

The installer in this version is a bit better (and there's an uninstall option), but otherwise it's fairly similar. Oh yes, I added a "Please Wait" screen to let the user know when it's loading. There are a few GUI improvements that make it a tiny bit easier to understand. Of course, fixing bugs always improves everyone's experiences.

### 0.4

Big steps forward here with a simple installer for each platform and region, which takes almost all of the interesting configuration problems away.

However, there is still much room for improvement. The user still has to run the configuration step of the grabber from a command line, which is decidedly unfriendly, and windows users have to set up the timezone info as well.

Linux users have still got it very tough with all the problems of installing XMLTV. We will just have to wait until the XMLTV project solves these problems. However, I feel I can expect Linux people to be much more clued-up than Windows people, so I'm not too worried about this.

Windows installation has become extremely easy (relative to previous releases) because the required XMLTV tools and Perl runtime are included in the jar file they download. Of course, they still have to download Java 1.4 first, but there's not a lot I can do about that in the immediate future.

### 0.3

0.3 still has a long way to go if it's going to be usable by the "my Mum" category of users, but it does have some improvements. For example, it notices when there are no listings and asks whether you want to go and download more. A lot of the wording has been made clearer, and the tick-boxes have been replaced with clickable programmes.

The UI generally has been improved, and makes it clearer (I think) what everything is for, and what you might like to do.

The major problem at the moment is installation. Java 1.4's Preferences features mean that a configuration file is no longer a problem, but I've made it very difficult for myself by using external tools through a command-line interface - this causes any number of problems, and there is still no decent installer which would sort some of these out.

When XMLTV gets a little maturer, and settles on an installation method (especially on Windows), then FreeGuide should follow and become easier on this front. The necessity of running the grabber configuration puts FreeGuide well out of reach of loads of users at the moment. I really don't know what to do about this - to wrap configuration with a GUI the XMLTV tools will need to have a consistent interface, which is difficult as different grabbers have different requirements.

Hackers are quite well served by 0.3, as the ability to have favourites selected using regular expressions has been added, thanks to Sun finally adding regexp support to Java. In fact loads of great things come from requiring Java 1.4 - you get XML parsing without an external library, the fantastic Preferences stuff, and regular expressions. And because this is an open source project, I can just decide that I want to require Java 1.4, and no-one can argue!

### 0.2

0.2 retreats slightly from my most strict ease of use requirements, as an acknowledgement that most users will be experts, mainly because it only works under Linux. It provides lots of unnecessary feedback from its downloading operations, because it is expected to encounter problems that I would like the user to be aware of and report to me. It also expects you to go to Tools and then Options just to download the listings the first time you use it, which is basically a mistake in the design brought about by a complicated system of checking whether it needs to jump you to here or there got a bit annoying and I took it out.

Hiding Download listings and Options (which allows you to download channels) away in the Tools menu is bad, but it if jumped to the right place automatically when needed, that might be appropriate as the normal user wouldn't need to know where they were.

Installation at the moment is fiddly, because you have to alter the config file manually, and I shall work on installers when there is time. This isn't a priority at the moment, because there are plenty of bugs to fix and basic UI stuff to be done.

The user doesn't get much feedback that the program is doing something sometimes - the current window disappears, and it can take a while for a new one to appear.

### 0.1

Version 0.1 didn't really work because I had to withdraw the listings grabber, so it didn't satisfy many of the users' requirements.