Suddenly, here at chez Derbyshire, it's 1996 again all over again. Instead of spending my days creating electronic guidance and online documentation in its wealth of different formats and styles, I'm back to writing real books. Ones that will be printed on paper and may even have unflattering photos of me on the back. And there'll be professional people doing the layout and creating the schematics. It's almost like I've got a real job again. I'll be able to do that "move all your books to the front of the shelf" thing in all the book stores I visit, and look imploringly at people at conferences hoping they'll ask me to sign their copy.
The reason is that we're producing a range (the actual number depends on how fast I can write) of books about the forthcoming version of Enterprise Library. I've been tasked with creating books that help people get to know EntLib and Unity, and get started using them in their architectural designs and application implementations. So the list of requirements includes making the books easy and enjoyable to read, simple enough to guide new users into understanding the basic features and their usage, deep enough to satisfy "average" developers who want to know more and learn best practices, and comprehensive enough to cover all of the major features that take over 1000 pages to describe in the online documentation.
They say that a job's not worth doing if it doesn't offer a challenge, so I guess this job is definitely on the "worth doing" list. And getting it all into books of about 250 pages will certainly be interesting as well as challenging. Maybe I can write very small, or use "txt speak". Need help using the Message Queuing feature of the Logging block? How about: "2 cre8 a msg q u use mmc & put name in cfg file thn cre8 logentry & snd. 2 c if it wrkd look in q". I can see my editor and proofreader having no end of fun with that approach.
But the hardest bit was actually deciding how (and whether) to provide sample code. Its likely there won't be room to print complete listings of all the code I use, which is probably an advantage in that readers can see and concentrate on the actual bits that are important. Of course, I need to build some examples to make sure what I'm writing actually does do what it's supposed to. So it seems sensible to offer the code to readers as well, like they do with most other programming books. But how should I present the code? As a pretty application with nice graphics and a delectable user interface? Maybe be all up to date by using WPF?
I remember when I first started writing books about "Active Server Pages" how we had no end of problems creating sample code that users could easily install and run. There was no SQL Server Express with its auto-attach databases mechanism, no built-in Web Server in Visual InterDev (this was the days before Visual Studio as we know it now), and you couldn't even assume that users had a permanent Internet connection (the vast majority were on a dial-up connection). So you had to create complicated sets of scripts and a setup routine, even for ASP samples, that registered the components you needed and populated the database, as well as providing a long list of prerequisites.
But things are much easier now. You can give people a zip file that they can just unzip and run. Even Windows Forms and WPF samples just work "out of the box". So, even though I haven't done much with WPF before, I thought I'd give it a try. I was doing OK with creating the form and adding some text and buttons, but then it came to adding a DataGrid. I thought maybe they'd forgotten to include it in the version of Visual Studio I'm using, but it seems that I wasn't prepared for the Wonderfully Perverse Features of WPF where you need to use Grids and ListViews and tons of stuff inside each one, then fight with Data Contexts and Binding Paths.
In ASP.NET I just grab a GridView and drop it onto the page. So should I do the samples as an ASP.NET application? That adds complexity with postbacks and maintaining state, and makes it hard to show some features such as asynchronous data access or cache scavenging. And it hides the real functionality that I want to show. Besides which, EntLib is really a library for helping you manage your crosscutting concerns, not a development environment for Web sites. How about Silverlight? Well, then I'm faced with a combination of the issues from WPF and ASP.NET. Maybe I should just take the easy way out and use Windows Forms. As a technology, I know it well and it provides all the features I need to create glorious user interfaces.
And then I remembered how long I've been writing code. Back in the early 80's, an attractive and intuitive user interface was one where you had a text menu on an 80 characters by 26 lines screen, and you could press any key you liked as long as it was one of those in the list. No need to mess about with sissy things like mice or trackballs, and no confusion about which things to click or where to wave your mouse pointer to see what things did. You knew where you were with applications in those days. And there's plenty of interest now in the old stuff such as text-based adventures and simple chunky graphic games like Asteroids and Space Invaders.
So why not follow the trend? Simple example applications that run in a Console window, have simple menus to select the specific sample you want to run, and use simple code to display progress and the results of the process. No need to run Visual Studio, the database will auto-attach to SQL Server Express, and readers can easily find the appropriate code in a single "Program" file if they want to read it all. In fact, I've seen this approach used by the guys from the data team here at Microsoft when they do presentations, and it really does seem to make it easier to see what's going on.
So that's where I'm going at the moment, at least until somebody else makes an alternative "executive decision" further down the line. What do you reckon? Do you want fancy interfaces for your code samples? Or are simple Console applications that focus on the "working parts" more useful and easier to understand? How about this for a flash-back to the past:
Or I suppose I could just publish the code as text files...