Writing Tips #3: Code first, write later

Posted by Warner Onstine on June 19, 2007

I’m going to share one of the tips that I got from fellow writer Matt Raible. I’m drastically paraphrasing of course as I can’t remember if he gave me this advice in e-mail or chat.

I recommend that you do a project first and then use that project as the basis for the work. It’s much easier. This is what I did with AppFuse and Spring Live/Primer.

I liked this approach and decided to take it with Tapestry 101 with (I feel) good success. I think it was successful on two fronts; first in learning a framework, second in teaching that framework to others.

This is contrasted to deciding what you are going to write about and designing a code example around that. From my perspective this is problematic for several reasons.

  • What you’re showing isn’t necessarily a “real-world” scenario that a developer would find in their day-to-day activities.
  • You will discover tips, tricks, and problems that you wouldn’t have run into in a pre-defined task.
  • Using a project (especially just one or two) throughout a book helps the reader through the Hero’s Journey showing them the way through the tangled forest by building on the knowledge they’ve just used.
  • Clearly defined problems are easy for reader’s to understand rather than just “Here’s something cool that you could use to do X”.

Currently I do a mix between using a pre-built project and writing on the fly. I know the project I want to build and generally what I want to show with it and then I start coding with a clear (non-book-related) goal in mind. But I don’t generally code all of it at once (as Matt suggested), instead I code the part just before I write the chapter. This helps solidify the ideas that I want to present in the chapter and helps me in my coding as well.

When coding I rely heavily on TDD now and it helps me immensely when I need to go back and try and explain something, I always start with the test. This is something relatively new that I will take with me on future projects (programming and writing).

Writing overall has definitely made me a better programmer as it has allowed me to dig deeper into a language than perhaps I would have if I weren’t writing about it. This in turn has made me a better writer because I am exposed to new ideas that I can share with the reader.

Share and Enjoy:
  • Print
  • Digg
  • Reddit
  • del.icio.us
  • Twitter
  • Facebook
  • Google Bookmarks
  • DZone

Next Language to Learn? 11

Posted by Warner Onstine on June 17, 2007

Definitely looking for feedback on this one. On my previous list I used to have the following as the next languages to learn and play around in. Of course the only true way to learn a language is to find a project to do in it (but I’ll figure that one out a bit later).

In no particular order:

  • Python
  • Ruby
  • Groovy
  • Objective-C

I went ahead and nailed Groovy (well still working on it but I have learned a lot in the short time I’ve dived into it). I still have my Programming Ruby book (and my Rails book) but haven’t had a chance to dive into those yet. Really would love to compare Groovy’s meta programming with Ruby’s in the near future. Python is still kinda on the radar, but mostly to learn how to manipulate tuples. Objective-C sits above Python for the moment.

Recently though some new (and not so new) languages have entered my list:

Here are some others that I might look into given the right impetus:

  • Lisp
  • OCaml – not so sure about this one

Functional languages are all the rage right now, so it would be good to know why ;-) . And Erlang and Scala both have Web frameworks that look interesting (Erlyweb and Lift respectively). Being a Web programmer I would like to investigate these as well.

What other languages are out there that would be good to learn? Why?

Share and Enjoy:
  • Print
  • Digg
  • Reddit
  • del.icio.us
  • Twitter
  • Facebook
  • Google Bookmarks
  • DZone

Writing Tips #2: Read Dave’s series on writing 1

Posted by Warner Onstine on June 16, 2007

I can’t recommend enough reading Dave Thomas’ series on technical writing (plus a podcast). Here’s a short synopsis of each, but I recommend you check them out for yourself.

  1. So You Want to Write a Book? – Why do you want to write a book? Am I passionate about what I want to teach people? What’s in store for me once I decide that I really do want to write a book?
  2. The Hero’s Journey – What is the reader’s journey through your book? How do you pace it? How do you make sure they get where they need to go?
  3. The Hero’s Journey: Are You Experienced – How to guid the user through successive learning in your book.
  4. Readers on Your Shoulders – How to think about the different types of readers as you’re writing your book, who are they and how do you communicate with each with the same material?
  5. Finding Your Voice – How do you sound like you while writing? This can be tricky and this will help.
  6. Wrandom Writing Wrules – Talks about what a good writing environment is for people (it varies), just writing and not worrying about layout issues, scheduling a time to write like going to the gym, not starting at the beginning of your book, cut and paste, interacting with others while writing, saving and archiving often, cross referencing and outlining. All good stuff to read for first time or veteran authors.
  7. Reviewers, And How Not to Kill Them – Talks about the process of reviewing and how not to let it affect you (too much, believe me reviewers can be tough).

I’ll try not to rehash these particular topics (although I will touch on a few these from my own perspective throughout this series).

Share and Enjoy:
  • Print
  • Digg
  • Reddit
  • del.icio.us
  • Twitter
  • Facebook
  • Google Bookmarks
  • DZone

Writing Tips #1: Never let the well run dry

Posted by Warner Onstine on June 16, 2007

I decided to start a new tag (Writing Tips) for those of you who are interested in writing tech books or articles. I hope that you enjoy this and find some value in my tips. Some of this will be a little regurgitation, but it will be from the perspective of things that have worked for me, your mileage may vary ;-) .

While working on my last book I ran into a writer’s block, things became difficult to get past and I was writing sporadically, so I reached out to the world-wide Web to see if others had come across this and found any solutions. One of the sites that I really enjoy reading for productivity is Merlin Mann’s 43 Folders and while reading it one day came across this excellent post on writer’s block. While these suggestions were really good it was actually one of the comments that led me to my final solution I will talk about here.

So, the actual quote from Hemingway is:

I learned never to empty the well of my writing, but always to stop when there was still something there in the deep part of the well, and let it refill at night from the springs that fed it.

While this is a great quote, how exactly should you apply it?

My solution was to pick up a little Moleskine notebook to keep just my writing notes. The other part comes in my “writing ritual” (sorry can’t find a link to it, it’s probably buried in 43 Folders somewhere). Here then is my ritual (again, you should come up with your own depending on what you’re writing or what you think you need to help you get in the frame of mind).

My Ritual

First, make sure you have a good 30 minutes or an hour to write, 30 minutes is good if you’re pressed for time or feeling stressed, an hour or more is what generally happens to me once the flow starts coming.

Then, I shut off my TV (I tend to write at home because I have an external monitor that makes it much easier to write). The other step to getting rid of external distractions is to open iTunes or my Shuffle and put on some music (it helps to drown out the silence and helps me focus, this may be different for you).

Next, I pull out my writing journal, a pencil and my eraser and set those aside.

The following step varies from time to time. Sometimes I will turn off any programs I don’t absolutely need (like Mail, Safari, etc.), but most of the times I just ignore them. If you do keep Safari (or IE, or FireFox) open I recommend closing all tabs except ones that you will absolutely need to keep down on the possibility of Web distractions. You’re here to write, not surf! ;-)

Then I open my writing tool (right now it’s TextMate, but I’ve used Word and other XML tools in the past).

Finally I open up my journal to the last entry and review my notes from the previous session. Once I’ve reviewed the previous entry I’ve written I will make a new entry with today’s date and write down the following:

  • What are my specific tasks for this session – in other words what do I want to write about or cover this session?
  • Start page count for what I’m working on – if it’s multiple chapters write those out separately, I do this as a heading
  • Write down the heading for the End page count

Now that I have my specific tasks laid out I pull up TextMate and start at the section I need to work on and start writing. Once I’ve covered most of what I wanted to write about or I’ve run out of time I go ahead and stop. It’s key here that you don’t do everything that you wanted to write about, you need to leave a little something in the “well” for next time.

Once I’m finished I go ahead and do the end page count and write that in (it really helps as a motivator!). Then I go over and write down stuff that I want to write or do next writing session which I will review the next time.

What should I write?

But how do you actually start this system? What if I don’t know how to even start on my topic?

A good first step is to see if others have covered something similar before (even if it’s a different technology, look at the techniques). Do you agree with their approach/disagree? Write these down in your notebook.

Why did this topic interest you in the first place? If you did it just to make money that’s ok, but there probably was at least something you liked about it to even accept the challenge. Write these down in your notebook.

Talk to your friends, co-workers, etc. Explain the problem to them, what you’re trying to address in the simplest terms possible. What interests them? What troubles them about the approach to the problem? Write these down in your notebook.

Write an outline. It doesn’t have to be super-detailed it should just cover the major points you want to hit in each section. Once you start on the section though you shouldn’t need it anymore it will change anyways. I’ve never had an outline I’ve stuck with 100%, but it always helped me get started and heading in the right direction. Once I got started though I pulled out my “compass” and found my own path to the end of the chapter.

I’ll have some more on getting started in my next Writing Tips.

Share and Enjoy:
  • Print
  • Digg
  • Reddit
  • del.icio.us
  • Twitter
  • Facebook
  • Google Bookmarks
  • DZone

Keeping a development journal 3

Posted by Warner Onstine on June 13, 2007

At last night’s presentation by Ted Neward one of the things he suggested during his debugging talk was to start keeping a development journal. This way you have a written record of things you’ve learned, tried, techniques, ideas, etc.

I like this idea for a number of reasons. I’ve always kept notes of meetings that I’ve been to or of ideas that I’ve had, but I’ve never done one specifically for development (at least at work). I also like the idea of a timeline, where I can go back through my journal and see what I was doing at a particular time, showing me the continuity of my development thought process. It also gives me the ability to track down items that I know happened during a particular time – “How did I end up tracking down that bug with accounting lines again?”

One of the problems I’ve always had is in seperating my personal projects from work projects (and personal projects from each other). I think that this approach, while on the surface looks good, is a bad idea. I periodically have gone through house cleaning and found several partially-filled notebooks of projects I’d started to think about but never implemented, but that had good ideas in them. So what do I do with those? They are in separate notebooks so I can’t combine them. What happens generally is I rip out the pages and recycle the notebooks, but I always end up with more partially-filled out notebooks.

I’ve also started using this blog as my own dev journal, but I don’t/can’t put everything up here (especially for all the work stuff I do as its mostly boring ;-) . I like to filter the stuff in my head (a bit) before posting it here. Starting today then I’m going to pick up a Moleskine and start my own dev journal with everything in it including work stuff. Then when that gets filled up I’ll start another. I don’t know how far to separate stuff yet (as I have other things besides development I’m interested in), I think I’ll get two journals, one for software and one for “other creative stuff”.

If you don’t like Moleskines you can always go for a lab notebook (the ones with the fake marble cover) as these have a sturdy cover that will last for a while and you can write the dates on the front cover (sorry couldn’t find a reliable link to these but you can find them in any office supply store).

If you’ve tried doing a development journal, what’s worked for you? what hasn’t?

Share and Enjoy:
  • Print
  • Digg
  • Reddit
  • del.icio.us
  • Twitter
  • Facebook
  • Google Bookmarks
  • DZone

WWDC Keynote 07

Posted by Warner Onstine on June 11, 2007

I hate to join in the chorus of “Me toos” but I was seriously disappointed in today’s keynote from Apple’s World Wide Developers Conference. Honestly it was one of the most non-event keynotes I’ve ever witnessed.

Let’s start from the top.

First, Steve goes over soem old ground with Leopard material with a few new bits in there on the new finder (Now with Coverflow!), stacks, quick look and some new iChat features. Ok, that was to be expected, every developer going to WWDC knew they were getting Leopard so no big surprises that Steve was going ot unveil some more of the OS.

Next came the announcement that Safari was going Windows. My first response was, hunh? My second was, “Well, I guess that is cool.” My third was “Crap, yet another browser to test all my Web stuff on.” Finally I thought, “This has to be part of some bigger plan that Apple has and isn’t ready to unveil yet.”

Then came “One More Thing”, iPhone third-party support through, uh, the Web. Alright, I admit that part of me likes this idea, being able to design a Web app that will interact with the phones features is cool, but this can’t be the solution, no way. Here’s why.

  • Offline mode – hello, if I’m on a plane or somewhere with crappy reception there goes the app I was just using
  • EDGE sucks – yeah, it’s better than GPRS but not by much. Apparently Cingular (nee AT&T) is beefing up their network to 2.5G but it’s still gonna suck. I’ve been on AT&T’s network – dropped calls, spotty reception, etc. So, every user is going to have to wait for your app to load through the browser before they can use it.
  • Two – Three steps to get to an app – now this is pure fiction right now as we don’t know if there’s going to be a way to store an app shortcut anywhere on the iPhone. Launch Safari, type in the address, probably login to said service (most of these are going to have to be secure in some way, it is your data)
  • Full power – you just don’t get the full power of the iPhone’s OS through the Web browser. Can anyone say games?

Overall I was very unimpressed with this year’s keynote. I was seriously hoping for a .Mac update (geez does it ever need it, talk about the red-headed step-child of Apple). Hardware updates I can wait for, but I was hoping for some real zingers this time out and it fell flat in my opinion. Now, I’m just going to sit back and wait for Leopard, hopefully fairly soon though I’m going to grab a new Mac Mini and start helping out on this project.

Share and Enjoy:
  • Print
  • Digg
  • Reddit
  • del.icio.us
  • Twitter
  • Facebook
  • Google Bookmarks
  • DZone

Groovy DSL steps 4

Posted by Warner Onstine on June 05, 2007

What are some of the basic steps that I’ve followed as I create my DSLs (especially with respect to Groovy)?

  1. What are your spoken and unspoken requirements?
  2. Who is the intended user? (this will help you decide some of the other questions later)
  3. Has this kind of problem been solved before?
  4. How did they solve it? (Language, Toolset, Techniques?)
  5. How closely does that solution match our requirements?
  6. What can we take away from that solution (if it doesn’t match the requirements)?
  7. What kind of DSL do you want overall? (Internal or External)
  8. Prototype, prototype, prototype – even if it is an Internal DSL you will still want to start out with a working prototype that your intended audience can play with and give you feedback on. This should be an iterative process to refine the language.
  9. External DSL – how to implement?

I will cover the first 8 of these, and I will leave the External DSL for a later post (sorry ;-) . For this I’ll use the steps that I’m currently going through on my own code to illustrate my own thought process.

Requirements

So, what are my requirements for my main two DSLs – QueryBuilder and ViewBuilder (this doesn’t exist yet, but starting on the planning right now). For QueryBuilder I wanted a clean syntax that makes it easy for developers to create constraints/restrictions on a database query. Ultimately the query could be executed by Hibernate, JPA, iBatis, whatever, so it should be ORM-agnostic. This actually isn’t too hard as they all have this concept of a criteria on an object/table and restrictions for that query. And the same goes for ViewBuilder, I want an HTML-like tree syntax that I can specify components in as well as attributes that will be applied to the view when it is built for me.

User

This one is easy, I am targeting Web application developers, initially I am targeting Tapestry Web application developers, but since the framework will be pluggable (probably around the 2.0 time) you can specify what specific pieces you want to use (Tapestry/JSF + Hibernate/JPA + Spring 1.x/2.x/Guice, etc.).

Has this problem been solved before?

In the case of the QueryBuilder, yes. Grails currently has an implementation called HibernateCriteriaBuilder. This has a nice syntax for specifying criteria and restrictions on that criteria. As for the ViewBuilder I don’t think this has been solved yet, but I will be looking. There is something similar in Groovy’s core for creating arbitrary HTML, which is close but not exactly what I’m looking for as I will need to generate more than just HTML from it.

How did they solve it?

Both of these were solved using Groovy’s BuilderSupport object which allows you to build up arbitrary “nodes” from a collection of method, property and closure calls. Very powerful and a little difficult to wrap your head around the first 10 times you look at it ;-) (alright, maybe it was just me, but that took a bit to fully understand what the hell it was doing).

How closely does that solution match our requirements?

First, for the HibernateCriteriaBuilder it actually will build up a real, live Hibernate criteria and use it, which unfortunately is not what I want. I need to generate the Java code that will come out of it. And the MarkupBuilder gets me part of the way there but not quite what I’m looking for.

What can we take away from that solution?

I decided to take away the syntax from HibernateCriteriaBuilder and looked at how they implemented it to see what I could do with that. And for the ViewBuilder I am going to extend BuilderSupport itself and use that to build up my nodes of whatever objects (so more than just plain HTML text, actually objects that represent things).

What kind of DSL do you want overall?

Definitely shooting for internal I think, but that doesn’t preclude having some kind of external DSL for the class creation stuff (that was a giant pain to do in Groovy/Java – just not all of the information I actually needed). So, having some kind of custom language for defining models could definitely come in handy down the road, but I haven’t decided anything yet. Plus, as I learn more Groovy and get feedback/suggestions I may stumble across something that simplifies my design greatly.

Prototype, prototype, prototype

This, aside from requirements and research is probably the most valuable step. Once you decide what you are going to do, how in the world do you do it? Especially if you’re dealing with Meta-programming (which can be a hard concept to wrap your head around)?

Here is where my experience will hopefully prove valuable to someone out there, here are the steps that I took when developing my QueryBuilder:

  1. Write the Unit tests first, start with the simplest test you can think of for how your language should work
  2. Run it – yeah I know its going to fail, but prove it to yourself ;-)
  3. Make it go green – whether you go ahead and create a simple class that has one method in it that does what you want do that
  4. Write another 2 tests – think about them, how are they going to change that class you just wrote, how much more complex is it going to make the logic you need to write to make sure you do what you expect.
  5. Fix the first test – is it time to extend DelegatingMetaClass yet? Or maybe try something simpler like a Category? Maybe the new ExpandoMetaClass will work. Try a few of them out, but I don’t recommend you dive right into extending BuilderSupport, not yet, not unless you have already used it before and understand fully what it does. Throw in lots of println "calling so and so with these arguments". These help identify that what you are expecting is actually happening while you write your DSL.
  6. Did that work? Good, write it so the next test succeeds.
  7. Continue doing 4, 5, and 6 until you are happy and ready to show it to someone
  8. Let them play with it, get their feedback. Rinse, repeat, refactor. (Here is where I would suggest you revisit the BuilderSupport idea, does it make sense? Remember not everything is an arbitrary nested tree, so not everything will benefit from using this structure.)

Well, I hope that this is helpful to someone ;-) . I really have gotten the DSL bug and (mostly) enjoy writing them. If you run into a weird error, throw it out to the Groovy list, someone should be able to help you out.

Addendum

I meant to add this in when I first started thinking about this post. When I started writing my QueryBuilder I didn’t start out with it generating anything but simple select strings. This helped me visualize the proper nesting of things without getting too complex. Once that was working right I changed my unit tests to expect the actual Java code I wanted back and changed the logic of what the DSL output.

Share and Enjoy:
  • Print
  • Digg
  • Reddit
  • del.icio.us
  • Twitter
  • Facebook
  • Google Bookmarks
  • DZone

MetaClass/Delegate warning

Posted by Warner Onstine on June 04, 2007

I’ve been working like a fiend on Chama and am just about ready for an alpha release (not much but will have some basic model and dao creation from a groovy dsl paired with database goodness). Like a good programmer I have been building stuff up in chunks so that I can test everything separately and now this morning I started finally integrating everything together and blammo! something strange was happening.

The first part of this puzzle lies in QueryBuilder.groovy, this class is a builder that eventually will get called from inside of a finder method (like findAll()) and get parsed by another meta class, but more on that in a minute. Inside of QueryBuilder I do some checks on whether we are passing a closure or not, if we are then I set the delegate class to the current QueryBuilder instance and call the closure. Thus, when the closure continues processing the next interior method of the closure gets called it calls the QueryBuilder again allowing me to create new restrictions inside the current criteria. Running my tests and everything works as expected. Now for the strange part.

In the next part I created a new class JavaModelDAOBuilder.groovy which will actually parse a Groovy script and call each method in turn through a custom meta class called MethodInterceptor. This meta class has now essentially taken first responder position to any method calls that happen on the Groovy script. Which actually sounds good on the surface, until I discovered that a closure is actually “owned” by its class. Now that the class has a meta class it will intercept all calls to the closure, completely bypassing the delegate.

After some digging I can see how this makes sense and after sending a message to the list I got some great responses. The final solution that Jochen(Blackdrag) came up with is to set a flag so that meta classes can “delegate” to another delegate. I think that this is definitely a workable solution, but for now I have some kind of hacky solution in the MethodInterceptor so that it looks for anything that the delegate should actually be handling and pass it back to that instance.

The good news is that it looks like this will be fixed in the near future, for those of us really pushing Groovy’s Meta Object Programming (MOP) and I think I’m going to be joining the dev list so that I can watch those conversations (especially the MOP-related ones). On another note I’m working on a few more Meta-related posts that will hopefully be of interest to some people ;-) .

Share and Enjoy:
  • Print
  • Digg
  • Reddit
  • del.icio.us
  • Twitter
  • Facebook
  • Google Bookmarks
  • DZone

Google Gears and Offline Web apps

Posted by Warner Onstine on June 04, 2007

If you haven’t heard it by now you’re probably under a rock, but this I think is pretty slick, offline Web apps through a browser plugin (firefox, IE, windows, mac, and linux).

Google Gears is an API that lets you run your Web application in offline mode. Now some people don’t agree with this, but it is coming (Dojo Toolkit Offline and Slingshot for Rails are being developed right now and I’m sure there are more).

And I do agree with some of his points, and I honestly can’t say in which direction RIA is going to go, here are the options I see:

  1. Desktop apps (swing, cocoa, whatever) that take advantage of web services and do mashups on a local app – probably requires something like Apple’s WebKit to do it well though.
  2. Flash apps that can run locally and access remote web services
  3. Ajax apps that can run locally and access remote web services
  4. Or … all of the above.

One of the arguments that David talks about in his post is that you aren’t on a plane, yeah well sometimes I do go to a coffee shop (like Starbuck’s) that charges for wifi that I really don’t feel I should have to pay for and all of the things I have to do (my tasks) are stored in a web app. It would be really nice to have something like this available to me in those situations.

Another idea that was brought up to me by someone on the Tucson JUG list is something like an offline P2P app, or ITunes style application, which makes perfect sense. It combines the best of both worlds, online synchronization with offline capabilities.

Personally I think that this is a really interesting development and its been going around (dojo has offline, there’s something called Slingshot for rails apps, etc.).

Where does everyone see this thing going?

Share and Enjoy:
  • Print
  • Digg
  • Reddit
  • del.icio.us
  • Twitter
  • Facebook
  • Google Bookmarks
  • DZone

Easy AdSense by Unreal