BlackBox : Category writing

Thinking about picking the Groovy DSL book up again

Warner Onstine — Wed, 26 Mar 2008 10:30:00 -0700

But before I do I thought I’d ask everyone out there (who are interested in such a book), what would you like to see in it?

One possibility I’ve been tossing around is to turn it into a techniques or cookbook-style book. I’ve been reading through “Designing Interfaces” by Jennifer Tidwell. In this book she organizes the interface solutions into different sections and goes through each one with an example and what it solves and when to use it. I really like this idea (but others might not). Originally my book was a “How do I get started designing DSLs?” and “What in the world are they and why should I care?”.

Another thing I’ve been thinking about is ditching the Java part and making it Groovy only. This appeals to me because I feel that Groovy is much cleaner to implement an Internal DSL than Java is. Can you do DSLs in Java? Of course you can, but I’m not sure that I can give it the best treatment because it isn’t what I’m passionate about.

So, sound off in the comments, let me know what topics you’d like to see covered, what challenges have you faced in writing a DSL (or API/Framework) that you would have liked someone to trailblaze for you to show the dead-ends first?

DSL book on hold...unfortunately

Warner Onstine — Tue, 30 Oct 2007 10:20:44 -0700

Well we got the first round of reviews back from the technical reviewers and there’s a lot of work to be done. So much so that we’ve decided to put the book on hold while we regroup and figure out if/how we are going to address the issues that the reviewers found with the book. In a lot of cases it is going to require a complete rewrite of the example (and hence the chapter itself). Personally I feel the core is there, but maybe the examples weren’t as fleshed out as they could have been.

Now of course I’m a little embarrassed that I announced the book before it was done, but that’s what happens sometimes. Not sure at this point whether or not the book will continue, taking some time to regroup/rethink things and see if it is something that I want to push forward with.

I will keep everyone up to date here on the progress of things once I’ve decided what to do. In the meantime I am going to get back to some of my back-burner projects (a few of which have some DSLs in them ;-).

DSL book in progress

Warner Onstine — Wed, 10 Oct 2007 09:44:00 -0700

Now that things feel a little bit more final to me I thought I would take this opportunity to announce the book that’s been keeping me from blogging. The tentative title is Creating DSLs using Java and Groovy and it will be published by Pragmatic Programmers. I started working on this idea after last years No Fluff Just Stuff where I saw Neal Ford speak on DSLs and I talked to him briefly about a project I was working on. His talk inspired me to push forward with using DSLs for code generation specifically using Groovy.

The book will cover both Java and Groovy techniques for writing DSLs, as well as have some general guidelines for writing DSLs. We also have a chapter on ANTLR and JavaCC for writing external DSLs using Java. I tried to cover as much as I could of Groovy meta-programming and some of the additional capabilities of Groovy that make it a good language to write an internal DSL on top of, but there’s only so much space ;-).

We just sent off the book for peer review, which means its about half-way finished, maybe a little more. We are currently shooting for a release date sometime early next year, which looks very doable at this point, but I expect a ton of edits to come back from this first review.

On a final note I just want to say what a pleasure it has been working with the PragProg crew. I love, love, love their book build system and my editor Susannah rocks. I have had a blast working with them so far on this book and am looking forward to finishing this up and getting it published.

Writing Tips #3: Code first, write later

Warner Onstine — Tue, 19 Jun 2007 19:48:47 -0700

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.

Writing Tips #2: Read Dave's series on writing

Warner Onstine — Sat, 16 Jun 2007 19:12:18 -0700

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.

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?
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?
The Hero’s Journey: Are You Experienced - How to guid the user through successive learning in your book.
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?
Finding Your Voice - How do you sound like you while writing? This can be tricky and this will help.
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.
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).

Writing Tips #1: Never let the well run dry

Warner Onstine — Sat, 16 Jun 2007 14:42:00 -0700

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.