Writing Tips #3: Code first, write later
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 1
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
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.
