just write click

← DITA and wiki - w/ho/w will (we/you) write Should I get a graduate degree in technical writing? Interviews with those who have →

Simplest of style guides

August 16, 2007 · 7 Comments

Ah, simplicity. Elegant. Succinct. Basic. Good.

Welcome to ASI, new writer. Here are the basics:

  • Write well, quickly, in the active voice and the present tense.

  • Put punctuation outside the quoted material.

  • Maintain gender neutrality. (”He” and “she”: bad. “They”: good.)

  • Replace semicolons with periods.

  • Use numerals for all numbers.

  • Make cross-references target-neutral.

  • Insert AIT variables.

  • Publish Word documents or HTML files only.

  • If it’s not here, look to The Microsoft Manual of Style for Technical Publications.

Categories: writing
Tagged: , , , , , ,

7 responses so far ↓

  • Gordon // August 17, 2007 at 1:50 am

    Ahh but how do you punctuate bulleted lists?! ;-)

    Love this idea, may well adopt it for my team, anything that lets us focus on writing and not worry about “Rule 342: Acceptable usage of brackets” is a good thing.

  • one man writes » Blog Archive » Recently read // August 17, 2007 at 6:47 am

    [...] Simplest of style guides ~ “Write well, quickly, in the active voice and the present tense.” [...]

  • Shannon // August 17, 2007 at 7:57 am

    To free yourself from the tyranny of your various English teachers and the pop-grammarians through the past 3 centuries, I recommend an excellent book by Joseph M. Williams called “Style”.

    Another excellent book, although much harder to find, is “Revising Prose” by Richard A. Lanham.

    When I was a pubs manager these two books were standard reference materials purchased for every writer who worked for me.

  • annegentle // August 17, 2007 at 8:00 am

    Ah, but the list itself serves an example of how bulleted lists are punctuated. :)

    Then again, I just checked our style guide for how to punctuate (or not) a bulleted list of single non-sentence items and we don’t address it at all that I can see.

    To be clear, this isn’t our full style guide, but I sure liked this summary. It certainly got me up and running quickly.

  • Gordon // August 18, 2007 at 9:45 am

    Yeah it’s a great summary, definitely “borrowing” this idea Anne.

    And I completely missed the ‘list as displayed’ angle, oops

  • diane fleming // August 21, 2007 at 1:55 pm

    I don’t get the one about punctuation outside quoted material - in American English, periods and commas appear inside the final quote…

    He said, “I think you are brilliant.”

    She quoted George Bush: “Let the doctors show their love.”

    But that’s probably not what you’re talking about!

    I love this idea - the simple style guide.

  • annegentle // August 21, 2007 at 2:03 pm

    Yes, that is what it’s talking about, and the punctuation rule has been the most difficult for me to become accustomed to. I don’t know the history behind that standard being established here at ASI. I’ll have to ask around.

    The punctuation outside quotes rule is standard British style, though. It certainly looks “incorrect” to my American-trained eye. :)

Leave a Comment