About the author.

Welcome to The blog of whall

Come on in and stay a while… laugh a little. Maybe even think. Read more...

Hi, This is Wayne. This is my site, my stuff, my blog, blahblahblah. The site itself is powered by WordPress and the Scary Little theme. I thought it was cool, and I still do.

June
14
2007
7:18 am
Categories:
Uncategorized
Tags:
Post Meta :

Or am I?  I constantly see mistakes in the Technical Writing of manuals.  Take this for example:

     Technical writing example msde sql server size limitation

I commented out the product name to protect the morons.

So anyway, notice how it says “the file can grow to 2 gigabits or more in size”.  First off, this should say “2 gigabytes“.  And that’s just the technical aspect of what’s wrong – grammatically it probably should have been rewritten anyway to “can grow to more than <whatever size>”.  No-one uses the term “gigabits” unless they’re talking about throughput, as in “10 gigabits per second”.  Transmission speed is in bits per second, and storage space is in bytes. 

Examples include:

  • “10 meg” – 10 megabits per second, or 10mbps with a lower case b
  • “gig” – one gigabit per second, or 1gbps

This kind of stuff bugs me.  There’s more wrong with the sentence.  For one, MSDE, the version they’re talking about, has a hard limit of 2GB (two gigabytes).  So in fact, it can’t grow to more that 2GB, because that’s the physical limitation of the “free” version of MSDE.  More recent versions, and the WMSDE version that shipped with Windows Sharepoint Services, doesn’t have the limitation, but for this manual to say it might grow more than that size is inaccurate.  So technically they should have said “can grow up to 2 gigabytes in size”. 

But even their use of the word “gigabits” instead of “gigabytes” tells me that no-one who knows this stuff was writing, editing or proofreading.  It takes 8 bits to make up a byte.   So at a minimum, they’re technically inaccurate with their use of the terms, but the worst of it is, they’re completely wrong!

ARGH!

And don’t try to defend them by saying “well, the programmer probably told them that, so they were just writing what they were told.”  Bleh.  Here’s part of the program itself:

        

Back in the old days, I was constantly impressed by how consistent user manuals were.  There was nary a spelling mistake, the format was consistent from section to section, and it was just plain accurate.  Sure, sometimes they lacked a certain readability, because most of the content was step-by-step of how to do it, not necessarily the “why” or the big picture concepts.  But I’ve noticed they’ve gotten better at that.

And while they got better at maybe including more overviews, conceptual diagrams, and more explaining the “why”, it seems a decline has occured in accuracy and just simple grammar, spelling and use of the right term.

While I’m at it, I might as well complain about this same technical manual’s propensity to mix Windows and DOS.  TSR’s?  Come on, really… <sheesh>.  This was from the “how to improve performance of your Windows application”.

     TSR terminate stay resident

I’m surprised they didn’t say “be sure to load HIMEM.SYS” and “don’t load DOSKEY.EXE”.  Or maybe they should have put in something about 8″ floppies.


Want to comment?

Hey, we all want to share our voice. And I particularly love comments, especially if you took the time to read my blog entry. I'll take the time to read your comment, I swear! But due to spammers, robots, and the fact that I want my blog to be PG rated, I need to approve the comments. This should be same day, but please don't get mad if it takes me a while to approve the comment.







Comment:


PLEASE help keep this blog family-friendly by refraining from profanity and vulgarity.


CommentLuv badge


Admin
tsk tsk

Ajax CommentLuv Enabled 336ad6ab990e8080f1c0ad1f892428a0