Write Specs In The Present Tense

0 comments suggest edit

I have a bad habit of writing specs in the future tense. Since the system I’m spec’ing doesn’t yet exist, it’s so easy for me to fall in the habit of saying things like:

  • This page will look like this:
  • At this point the system will do this.
  • The system will display that control here.

instead of:

  • This page looks like this:
  • At this point the system does this.
  • The system displays that control here.

So what’s the big deal? Well there’s two big deals. Number one is a question of written aesthetics and the other is a more practical consideration. Ok, so they’re not all that BIG a deal. But let me continue.

Aesthetically speaking, using the present tense sounds more active and interesting. Remember all those lessons about active voice and passive voice in high school English? I think it’s made me paranoid.

Secondly, and more importantly, is that after you build the system and someone comes along and refers to you spec as a piece of documentation, it sounds kinda funny to say the system “will look like this” when it already “does look like this”. You can argue that the system doesn’t respond till the user interacts with it so that saying “When the user clicks here, the system will navigate there” isn’t so off the mark. See my first point in response to that point. I thank you for your time.

Found a typo or error? Suggest an edit! If accepted, your contribution is listed automatically here.

Comments

avatar

One response

  1. Avatar for Hilton Chiramel
    Hilton Chiramel August 21st, 2007

    Hi,
    I'm a technical writer for a spec team. I do agree with your points. But I feel that when an action requires user interaction, it's better to use simple future.
    Compare the following sentences:

    "When the user clicks here, the system will navigate there"
    "When the user clicks here, the system navigates there"