Tag Archives: writing_skills

Uncategorized

Engineers don’t get capitalization

They also don’t get a number of other things, like punctuation and grammar.

When I was in 1st grade, my teacher gave us an assignment to write something – you know, on those tables with the huge writing lines with the dashed line in the middle so you’d know how big to make your lower-case letters.

Anyway, I asked the teacher if we should use capital letters or not. She said something to the effect of “Either one is fine.” As a 7-year-old, I interpreted her a little too literally, and I wrote things like “I WenT tO ThE paRk.” My grade on that assignment was really low, and the teacher explained that she meant for us to use capital letters all throughout or not at all.

Engineers aren’t much better. What’s even more surprising is that these documents that I’ve read were written by senior engineers who have written numerous documents like these and are very highly paid. The documents I’m talking about have phrases like “Signal Sample Rate” and “Tuned Signal Bandwidth” where they should be “Signal sample rate” and “Tuned signal bandwidth.” These are pretty benign examples – there are far worse ones, but I’m not permitted to reproduce many of them here.

It’s baffling to me; I have no idea why it seems to some engineers that words like “signal” need to be capitalized when they aren’t proper nouns or part of a title or any other category of words or phrases that need to be capitalized. It’s very distracting to read documents like this because instead of focusing on the subject matter, I think about how badly the document was written.

Update: I just realized that I previously wrote a post very much like this one. I’ll leave this as is, but add that the duplication illustrates that I see poorly-written documents on a regular basis. I’d be embarrased if I wrote such a document.

Uncategorized

Writing is a Lost Art

Notice how the title of this post is properly capitalized: All the Meaningful Words of a Title are Supposed to be Capitalized.

I am in the middle of reading a technical document at work. It’s the latest of several documents I’ve read at work that are badly written. One of the most annoying things I’ve found that people do here is capitalize words that shouldn’t be capitalized; like all nouns, for example. A sample:

Each Service publishes a Contract with …

and

Since the Kernel acts solely as a runtime environment for Services…

The document is littered with sentences like the above. It’s highly distracting. The word “Service” should not be capitalized. Neither should the words “Contract” or “Kernel”. They aren’t proper names nor do the refer to some individual object or idea.

The writing is too familiar (too many instances of phrases like “we did this…” or “You will find it easier to…”). It’s also very preachy; the document in question is supposed to be an overview of a particular application and the associated frameworks and libraries. Instead, it’s a rambling description of portions of the subject with whole paragraphs devoted to telling me why they think .NET is peachy-keeno and how they don’t use WSDL but have special interfaces for what they define as a service. Not only does the author seem to reveal a misunderstanding of services and what WSDL actually is, he couches it in a way that makes him seem willfully ignorant.

Anyway, I could go on and on about the poor quality of writing that I see on a daily basis. That’s actually one of the reasons I maintain this blog; it’s a way for me to regularly exercise my writing skills – with complete, properly capitalized sentences and other elements like good grammar and oft-unused vocabulary.