Writing Tips for PragProWriMo

Posted by Warner Onstine on November 01, 2009

First we had NaNoWriMo (National Novel Writing Month), then NaNoDrawMo (National Novel Drawing Month), now we have PragProWriMo (Writing a Tech Book for the month of November – named after Pragmatic Programmers, a tech publisher).

So, I thought I’d share a few writing tips for those of you attempting to write a tech book this month. There are also some great tools out there that you might not be aware of. I’m not familiar with all of them, but I’ve provided links and reviews for you to make your own decision.

Tools

(Apologies in advance, I’m a Mac person so most of these tools are for Mac people – sound off in the comments for other platform-specific tools you use.)

  1. Scrivener – I like this app a lot so far, because it’s great for collecting bits and pieces together and organizing your thoughts into chapters as you write. Here’s a longer review of it. You get a 30-day evaluation license (and I mean 30 days of writing, not from when you open the application). (Special deal for NaNoWriMo participants.)
  2. Storyist – This is one I would like to try, and I’m glad they’re going with the 30-day evaluation license as well (not sure if it’s like Scrivener’s 30 days of use license or not). Here’s a review of it. (Special deal for NaNoWriMo participants.)
  3. StoryMill – I’m not very familiar with this tool, but a here’s a review. (Special deal for NaNoWriMo participants.)
  4. UlyssesHere’s a review of it. (Special deal for NaNoWriMo participants.)
  5. Nisus Writer Express (or Nisus Writer Pro) – Here’s a review of Express.
  6. CopywriteHere’s a review.
  7. WriteRoom – This is a bare bones “just write it” editor. Nice to take away all the distractions and focus on writing.
  8. TextMate – This, combined with some of its plugins make this a very good tool for writing a tech book.
  9. Pagehand – This looks like a very interesting Word Processor. Not sure if I’d use it to write a tech book. It does look like it could handle layout a lot better than Word can, though.
  10. Microsoft Word (or free alternative OpenOffice.org) – Honestly, I’ve written two tech books in Word, and I would not recommend it to anyone. It is absolutely horrible. Don’t do it. Save yourself some pain and anguish, seriously. I don’t know about OpenOffice, but I would imagine it would be similar. This leads us to our next question – choosing your format.
  11. Emacs or vi – I’m not even going to go there. If you know what these are then you’re already using them (or decided not to).

What format should I write it in?

Ok, so if I’m not going to write this in Word, what do I do?

There are several format options available to you to write your tech book in.

  1. First up is DocBook or Simplified DocBook, which is an XML format. It was meant for writing books in. There are stylesheets available that will convert your book over to PDF format so you can see what it will look like written out.
  2. LaTeX is a document preparation system (which to me means you shouldn’t be writing in it) and is for the hardcore geeks among you. I wouldn’t write a book up in LaTeX myself, but if you like it and want to do it that way, go for it. Personally, I’d rather convert a DocBook document to LaTeX, and then take LaTeX to PDF.
  3. Scrivener has built-in support for the MultiMarkdown format, which is an extension of Markdown. This is a nice, lightweight format that is easily transformable to PDF.
  4. No formatting at all. This is certainly an option. Just write, get your words (and code) on paper and format it later.

How do I write (or choose what to write)?

Hopefully you already have something that you’re passionate about. If not, then I would recommend you not undertake writing a tech book. It is truly a labor of love and passion. Your passion shows through in your writing and helps readers become involved in the story of becoming a better programmer, sys-admin, photographer, etc. If you aren’t passionate about your subject, then that will show through too and your book won’t be successful in getting your readers fired up about the topic.

That said, first you should read Dave Thomas’ series on technical writing. Here are some highlights from that series. Once you’re done, come back here for some more tips.

Ok, all done reading the highlights? Good. I also recommend the “Code first, write later” technique. With this technique you pick a project that you are going to do from start to finish with the reader, walking them through the basics and helping them learn some things along the way.

Finally, we get down to the actual business of writing the book itself.

  • Never let the well run dry – This tip came from Hemingway, and I applied my own technique to it.
  • Use a time management technique to focus on writing – Using something like the Pomodoro Technique can help you during your writing phase. Just write for 1 or 2 Pomodoros (1 hour), then up it to 3 or 4. If you feel like doing more (and you can), go for it! See how much you can get written that way.
  • Set daily and weekly goals – Start small at first, then increase. Don’t try shooting for 10 pages a day right away, get a feel for how much you can actually do. 2 or 3 pages a day to begin with is a decent pace for a tech book. Once you set your goal, track it to monitor your progress.
  • Track progress on your goals – Just as with any goal, if you aren’t tracking your progress, how can you know if you are going towards it or away from it? Of course that means that your goal itself has to be trackable in the first place (see SMART goals for more information on setting goals).
  • Be accountable – Write on your blog or Twitter what your progress is – be accountable to someone besides yourself. This will help you stay motivated and want to update others on your progress (and maybe help motivate them as well).

Do you have any writing tips of your own that you would like to share? Add them in the comments!

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

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

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

Easy AdSense by Unreal