Share via

Technical Writing

  • Article

Someone forwarded me a link to one of Jean-Luc David's blog entries in which he lists a few techical writing observations. I just finished the second draft of my very first technical article which was probably one of the hardest writing pieces I've ever had to compose in my youthful life. I thought I'd take the opportunity to thrown in a few observations of my own.

  • Talk to people about what you are going to try to accomplish with the article. This is the best time to get feedback on your ideas.
  • As Jean-Luc mentions, write your code first. Do a code review or two with a peer to ensure that your code is solid, but do not start writing your rough draft until you have all of your code in place.
  • An outline is always a good start. Staring at a blank word document for hours on end while attempting to decipher all of your thoughts is not going to get you anywhere. Start with an abstract outline, and then enter an iterative process of breaking that down until you have enough details to get started on your first draft. This also gives you a good idea of the additonal research that you will have to do.
  • With this being my very first article, I really struggled with writer's block (and on a few occasions, writer's cramp). Jean-Luc suggests taking a break and that's the very same advice I'd give. A visit to the local coffee house doesn't strike my fancy, instead I hit the ice rink for a quick pick-up hockey game.
  • Get as much feedback as you can possibly get throughout the drafting process. If you're stuck on a paragraph, ask someone to read what you already have and tell you what they think is missing.

Comments

  • Anonymous
    June 22, 2004
    Thanks for the ideas and thoughts. If you see my latest blog entry - I've posted some good links for technical writers.
  • Anonymous
    July 22, 2004
    The last point

    >Get as much feedback as you can possibly get throughout the drafting process. If you're stuck on a paragraph, ask someone to read what you already have and tell you what they think is missing.

    was very insightful. I follow the rest of the ideas you mentioned almost as custom. I never considered getting the "obvious missing link" from a hallway reading. Great idea.