Pronouns in technical writing.

When doing technical writing, or for that matter most forms of writing , we need to be able to refer to people without always identifying their gender.  The most common reason, at least in my writing, is that I am often speaking of some indeterminate person whose gender simply does not matter.  In my technical writing, I often speak of some generic DBA and what the best approach they could take to solving a problem is.  In my legal writing, I often speak of some generic person whose gender is irrelevant.  Often, the best approach is to recast the sentence in the plural, but when that is awkward or undesirably, I prefer the singular “they”.

While still somewhat controversial, and possibly not an ideal solution, the singular “they” seems the best answer to English’s lack of a good singular pronoun for people that is not gender specific.  It has been in use for quite a while, and its usage is becoming more accepted.  The Washington post recently allowed the singular they, although in somewhat limited circumstances, in a memo.  Merriam-Webster.com hosts a video discussing using “their” as a singular possessive pronoun.

There are several other options that could be used instead of the singular “they”.  “He or she” is commonly used in many places.  In one article I recently published, the article editor and I discussed whether to use “he or she” or “they” before we finally settled on “they.”  While somewhat a matter of taste, I find “he or she” to be unnecessarily long and wordy.  It becomes tiresome, especially when used several times in an article.  I think things like “s/he” and “he/she” are worse.  They are awkward when reading and not directly pronounceable.

An author could simply use one of “he” or “she” as a pronoun referring to a generic person without any implications for their gender.  There is in fact some indications, according to Wikipedia, that it is a long tradition for “he” to be used generically without specific reference to males.  But that has its own complications.  Aside from not being inclusive on its face, it could lead the reader to think the author is specifically referring to one gender or the other.

Perhaps the best solution would be to introduce a new word in English.  Attempts have been made to do this with proposals for “zhe”, “thon”, and “co”, but none of those have been widely adopted or accepted.  Unless English standardizes on a new addition, I think the singular “they” is the best choice for a gender neutral pronoun when the sentence cannot be gracefully rewritten to avoid the pronoun entirely.

Advertisements

Keep it short

I have been thinking about resumes a great deal lately. Since I recently passed the Bar Exam, I have been revising and sending out my resume in search of a legal job. At my current job, I have also fairly recently reviewed several resumes from new applicants. I cannot claim to be a resume expert, and I will not try to give any detailed advice. But there is one thing that many people that have given me advice have all agreed on, and that I wish the people sending in resumes that I have to review had remembered.

Keep it short.

When I looked into resumes before while looking for technical jobs and more recently when I was looking into them for legal jobs, virtually everyone recommended keeping them short. When I review resumes, I distinctly prefer them short. Exactly what short means varies somewhat by who is giving the advice, but some of them recommend strictly keeping it down to one page and a few others say that two is acceptable. When I have reviewed resumes at different times, a second page has never bothered me. But I have been rather annoyed when I have reviewed resumes as long as sixteen pages.

Generally, keeping it short will help ensure that the important information is easy to find and review. The unimportant information does not need to be there at all. There are occasions when a potential employer wants something longer and more detailed. However, those employers will generally make that clear by asking for a C.V. or even a portfolio rather than a resume. With a bit of help from a skilled counselor at my law school, I ruthlessly trimmed my resume down to one page, and I think it is stronger now that it is shorter.

Some Jargon from the SQL Server World

Not long ago I wrote about how to write well about SQL Server, and one major point was that jargon should be used sparingly and carefully.  Tied to that, I thought it might be beneficial to collect ten of the more commonly used jargon phrases in the world of SQL Server literature.  In doing so, I hoped to provide a concise list of terms that people joining this community might wish to be familiar with.  I also thought it would serve, as a reminder to the seasoned database professional that these were jargon and might not be understood outside our community, many even have an entirely different meaning in other communities.

To expand slightly on what I said in my previous post, jargon is not always a bad thing.  Sometimes there simply is no non-technical word to express a concept, or the technical term expresses it much more succinctly.  Some in sociology even say that jargon can help with group identity and group cohesion.  Yet, it can make communicating with those outside of the group, or new to the group, difficult.  Even those well versed in the terminology can find reading something which overuses jargon tiring and difficult to follow.  Jargon does not necessarily need to be avoided, especially when the target audience should be familiar with it, but it should be used sparingly and with care.

Here, I am focusing on terms which are relatively common within the SQL community, but which would likely be unfamiliar to those outside of it.  I am intentionally avoiding terms like IAM/PFS[1] that are relatively rarely used in the community.  I am also skipping words like table, row, and query that are amoungst the first things anyone working with SQL Server will learn.  Instead I am focusing on the words that are common but not elementary within the SQL Server community or those that are so common that people readily forget they are jargon, and I am not trying to be comprehensive even there.

1.    DBA  – The job title held by many who work with SQL Server is largely unknown outside the technical community.  Even spelling it out as “Database Administrator” has earned me quizzical looks when I talk to people outside of the computer professions.  I generally describe myself as a programmer when asked unless I know the other person actually has a technical background.  The abbreviated form also overlaps with multiple other terms, such as “doing business as” in the business/legal communities and “Doctor of Business Administration”.

2.    Normalization – Normalization is a way to organize tables and the relations between them to help reduce redundancy.  Under the right circumstances, normalization can help reduce the size of the data files, guarantee certain types of internal consistency, and make the database more flexible for future changes.  However, it can, under certain circumstances, come at a performance penalty and potentially some increased complexity in programming since it frequently involves creating more tables which must be joined together.  The term normalization is shared with many other fields such as sociology and statistics, where it refers to a way to remove certain types of statistical errors.

Normalization is a deep topic and is discussed in some detail in articles such as:

The Road to Professional Database Development: Database Normalization by Peter Larsson

Stairway to Database Design Level 9: Normalization by Joe Celko

3.    3NF – The Third Normal form is the normal form most often sought after for practical database implementations.  It was loosely summed up by E.F. Codd saying “Every Non-key attribute must provide a fact about the key, the whole key, and nothing but the key.”

4.    Codd – Speaking of E.F. Codd, many serious students of relational databases are likely to be familiar with his name.  He was a researcher for IBM who is credited with inventing the relational model for databases and created much of the foundations of the theory behind relational databases.  The phrase “so help me Codd” is also occasionally, jokingly, added to the description of 3NF.  His name is also attached to the Boyce-Codd Normal Form (BCNF, sometimes called 3.5NF).

5.    RDBMS – Relational Database Management System.  MS SQL Server is a prime example of this, but so are Oracle, MySQL, SQLite and others.  Relational databases are based, although sometimes loosely and with compromises, on the relational model first described by Codd.  Relational Databases can be contrasted with OODBMS[2] like ZODB and Key-Value Stores like BigTable.

6.    ACID – Atomicity, Consistency, Isolation, Durability.  ACID describes properties of a reliable database transaction.  To perhaps oversimplify, if a database is ACID compliant then either an entire transaction completes and is committed or none of that transaction is committed.  In SQL Server, the database engine provides mechanisms to ensure that transactions are ACID compliant.[3]   ACID is often contrasted with the BASE[4]consistency model, which describes some types of NoSQL databases.

More information at:
DBAs on ACID by Tony Davis

7.    PowerShell – PowerShell is a command line shell and scripting tool.  It permits access to the .NET framework including SMO, which permits relatively easy control of SQL Server.  There are many online resources for PowerShell, including:

Introduction to Windows PowerShell for the SQL Server DBA by Edwin Sarmiento

Exceptional PowerShell DBA Pt1 – by Laerte Junior

 

8.    CRUD – Create, Read, Update, and Delete.  They are four of the basic functions of any persistent storage system, including databases.  This comes up frequently in the context of describing an application that does CRUD work on a database, especially if that application does nothing but provide a convenient front end or GUI for users to perform CRUD operations on the database.

9.    GUI – Graphical User Interface.  This of course is a term that is used widely in tech circles, and programming circles in particular.  Most users, especially the technically sophisticated ones will already be familiar with this term, but not all.

10.  ETL– Extract, transform, and load.  When discussing databases, this is generally the process of preparing a data source and then loading it into the database or data warehouse.  I have occasionally seen this used in reference to removing information from a database and presenting it in a more user friendly format, but that seems to be a less common use.

Talking about SQL Server in particular, SSIS is one of the main ETL tools used.  But practically any programming language can be used for the purpose.  I tend to make extensive use of Python for ETL tasks that involve substantial preprocessing of the data.


[1] Index Allocation Map/Page Free Space.  I only really learned this one myself when I was investigating some surprising results on a performance test.

[2] Object Oriented Database Management System

[3] There are some subtleties here though.  Handling Constraint Violations and Errors in SQL Server by Phil Factor has details on some of the factors that affect rolling back transactions.

[4] Basically Available, Soft State, Eventual Consistency.

Writing About SQL Server

  1. I.              Introduction

I recently submitted my entry for a writing competition as part of my continuing education.  While I was preparing for the contest, in which we had one week to create the best entry we could on a topic they provided, I starting doing considerable research on the topic of writing well.  I thought it might be beneficial to organize what I found and provide it to the community.

I will be focusing primarily on SQL Server, because that is what I know, but most of these concepts are fairly general and should be useful in most forms of writing.  In looking at writing in the context of SQL Server, I will consider style and techniques for doing the actual writing.  I also look at how to find things to write about and ways to improve writing skills.

  1. II.            Style
    1. a.    Remember your audience and reason for writing

“Remember your audience” is repeated constantly, almost to the point of being cliché, when looking through discussions on writing.  But it really seems to be one of the most significant factors.  The target audience and reason for writing can affect the style, word choice, and what is said.  I write differently if I am sending a quick e-mail about the groceries to my wife than I do when sending a status report to my boss and both are different from how I would write an academic paper meant for submission in a class.

There are of course an enormous number of variations of target audiences and reasons for writing, but here it is worth looking at the normal cases when writing about SQL Server, specifically the writing of technical articles.  Technical articles tend to be targeted at being informative rather than persuasive, which means they can focus on objectivity rather than advocating a position.  It also means that generally opinions are not helpful, though there is some room for discussing taste and personal preferences, especially in informal writing.

Technical writing about SQL runs the gamut from being highly formal to fairly informal.  The differences hinges of course on how things are presented.  In formal writing, grammar tends to be more important and there may be conventions to that specific type of formal writing.  For instance, some organizations suggest that in formal writing contractions should be avoided and acronyms should be spelled out the first time they are used (even if the target audience should know them).  Some suggest that the use of any form of the words “I” and “you” should be avoided as they can add the appearance of subjectivity.  For instance, before I went back to school, I used to read Scientific American regularly.  Most of the authors in the articles went to pains to avoid using “I” or “we” and instead said things like “The author”.  There are a wide variety of types of formal writing with different style guides such as the Chicago Manual of Style that is used in the competition I was preparing for.

More informal writing on the other hand, might eschew many of those conventions and use contractions or “I” readily.  One of the main benefits of less formal writing is that it permits a more conversational style, which many people find easier and more pleasant to read.

  1. b.    Use passive voice only when there is a good reason.

I remember one of my middle school teachers used to rail against the passive voice.  She would always say we should never use the passive voice and deduct points for every time we used it in an essay.  It used to drive me crazy.  I intuitively felt (though I’m not sure I actually knew the word intuitively then) that there were some times when it just sounded better.  More than that, the passive voice persisted in English and other languages, which seemed to indicate there was a reason for it.

Though I generally think she was an excellent teacher, I have to respectfully disagree about this.  There are times when the passive voice is the right choice.  But we disagree only in degree.  The active voice is normally the better choice, even if the passive voice does have its place.  The active voice is easier to read and generally it is more expressive.  The passive voice also tends to result in longer sentences.  The passive voice tends to be horribly overused.  For a trite example, “Suzy kicked the ball” is shorter and simpler than “The ball was kicked by Suzy”.

I have adopted the approach of going back during editing to find sentences that use passive voice.  Then I ask myself why I used it there.  If I have a good reason, I leave it in passive voice.  Otherwise, I rephrase it in active voice.  This of course leads to the question of what constitutes a good reason.

One reason is that you may not know who performed the action.  Or you might know, but might not want to say for some reason.  For instance even if you know Jack, the new programmer, was the one that deleted the backups, you might just want to tell the manager, “The backups were deleted” instead of “Jack deleted the backups”.  This puts the focus on the backups and the current situation and avoids laying blame.

Along those lines, even if you intend to indicate the actor in the same sentence, the passive voice lets you emphasize what was acted on.  “The production server was ruined by the rainwater.”  Yes, we know that it was the water doing the action.  Yes, “The rainwater ruined the production server” is shorter.  But what is important is that the production server is dead, how that happened is secondary.  The passive voice lets us make it secondary grammatically as well.

Finally, the passive voice can be used to give commands or make suggestions without phrasing them as commands.  For instance, “It is generally better to avoid passive voice” can come across much less harshly than a prohibition of “Never use the passive voice”.

  1. c.    Grammar and spelling matter, but not as much as content and flow.

C.S. Lewis wrote in a letter “’Good English’ is whatever educated people talk; so that what is good in one place or time would not be so in another.”  It is easy to spend inordinate amounts of time focusing on spelling and grammar without improving the actual writing itself.  For some words, spelling varies by region.  In England, “colour” is considered correct while in the U.S. “color” is used.

Worse, an absolute devotion to certain rules of grammar can lead to awkward sentences.  I was told throughout school that a sentence should never end in a preposition.  Wikipedia’s list of Common English usage misconceptions says that this was not always necessary.  Either way, striving too hard to avoid ending in a preposition can result in odd sentences that are hard to read.

But spelling and grammar do matter.  Truly sloppy spelling or grammar simply comes across poorly and gives a poor impression.  They can distract the reader, and in some cases actually change the meaning of the sentence.

As with almost everything in writing, audience and purpose matter.  The more formal the writing is supposed to be, the harder I try to ensure the grammar and spelling are correct.  For the right audience, I even try to avoid preposition at the end of sentences. For some situations, like a writing competition, the dictates of a specific style guide may be enforced.

  1. d.    Prefer short, simple words and shorter sentences.

This again is common advice.  Paul Graham advised writers to “use simple, germanic words”.  George Orwell said, “Never use a long word where a short one will do.”  Short, common words, and short, direct sentences, are simply easier to read and understand.  Use long, unusual words and long, complicated sentence structures only when they are necessary to convey the idea.

  1. e.    Consider carefully the use of jargon

If you can avoid jargon, or terms of art, you generally want to.  George Orwell said “Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent” in his Politics and the English Language.  But he was speaking specifically of political speech, which is generally meant for a mass audience, and even he limited it to times when a non-jargon word was available.  In writing about a technical topic like SQL Server, there often is no simpler word, or using one word of jargon would permit you to avoid a lengthy phrase.

How hard you should work to avoid jargon and what techniques you use to minimize it thus depend a on your target audience.  For instance, if I am writing a note to a group of senior DBAs, I will use “3NF” with abandon and expect them all to know what it means.  I express in three characters a concept that takes several sentences to convey clearly and whose implications fill numerous articles.  But I would only do that if I knew I was writing for a group of database specialists.  If I were writing to developers that were not specialists in SQL, I would probably write out “Third Normal Form” and might even provide a brief description to at least hint at what it was.  If I were writing to include a group without a technical background, I would try to avoid the term entirely if I could, and would definitely include a brief description if I felt it impossible to completely avoid it.

  1. f.     Minimize the use of adverbs.

Mark Twain is often quoted as saying “If you see an adverb, kill it”.  Yet, adverbs can be helpful.  They can help clarify a situation or describe it more graphically, and obviously they can provide emphasis.  I have used a few already in this paragraph, and even Mark Twain’s The Adventures of Huckleberry Finn makes frequent use of them.  But they are often overused, and text is frequently improved by removing them.

Like the passive voice, I have started looking for adverbs when I edit.  When I find one, I don’t immediately kill it, but I do ask if it is serving a purpose.  Even when it is serving a purpose, I consider whether I might do better with a stronger or more descriptive verb or adjective.  Only if it is serving a purpose and can’t be easily supplanted by something better would I leave an adverb in peace.

I give particular attention to the word “very”.  It adds emphasis, but rarely in a way that is truly useful.  Normally, I find that “very” is adding nothing of substance and purge it.  Sometimes, I find that the emphasis is necessary, but then I can normally use a stronger adjective to better effect.  For example, “Tarantulas can be very big.”  The “very” adds little.  If I just want to convey an impression of the size, “Tarantulas can be huge.” is both stronger and shorter.  But if I want to actually convey details then “Tarantulas can have bodies up to ten centimeters long.” is more precise.

  1. g.    Provide the readers a roadmap.

It generally helps to give readers an idea of what you are about to talk about prior to diving in to technical details.  This helps the text appear organized and well thought out and helps the reader to know what to expect.  It also helps to find something quickly when you are referring back to a document or looking for a specific answer in a longer document.

There are a number of techniques that can help provide a road map.  One of the more obvious ones that is particularly helpful in technical documents is to provide headers and sub-headers.  Within the writing itself, it often helps to introduce a topic briefly before going into in great detail.  Especially in technical writing, this can involve simply stating outright what you are going to discuss in that document or topic and why it is important.  It is also helpful to clearly and cleanly indicate when you are changing topics rather than continuing and elaborating on the last one.

  1. III.           Technique
    1. a.    Have a plan, but don’t be bound by it.

The best way to ensure that a text is well organized is to organize it from the beginning.  A plan can bring both structure and purpose to any writing project and writing without a plan is likely to be difficult to read and full of unrelated digressions.  It is difficult to make anything with a complicated structure without a plan ahead of time.

But a text written with utter devotion to the original plan is likely to be inflexible and brittle.  The process of writing helps you think, and it is possible that you will come up with new ideas or discover new facts while writing.  Sometimes those will even be surprising, as I was surprised by some things I found while writing the comparison between SQL Server and SQLite.  You might even find that the original plan needs to be substantially revised either because of something new you found or simply because you find that the structure you planned to use is not working well.  A plan is extremely helpful, as long as that plan is flexible.

  1. b.    Edit and Rewrite

A common maxim in writing fiction is “Write less, rewrite more.”  Similarly, Paul Graham advises getting out a first draft as quickly as possible and then rewriting and indicates he often spends nearly twice as long editing and rewriting as he did in making his initial draft.  While that much editing might not be necessary for a technical article, which tends to be more straightforward and a little less concerned with tone than either fiction or Paul Graham’s essays, editing is of vital importance.  I have always been able to improve anything I have written by going back over it carefully and making small tweaks, and then repeating the process.

When editing, I tend to make several passes, and there are a few things I focus on.  The most important thing for me is to make sure I am actually saying what I intend to say.  I look for places where my sentences are ambiguous or my structure is unclear.  I also try to look for places that don’t flow, or don’t sound right.  Reading the paper aloud can help with this, though I skip equations or blocks of code when doing that. Naturally, I also look for any actual mistakes I made or anything I said that I might need to double check or add a reference for.  Then I look for specific details, like unnecessary adverbs or over-use of passive voice.

On anything that is actually of real importance, I try to make at least two editing passes, once for large scale issues and the second focusing on the small scale issues.  More than two editing passes can certainly be appropriate, especially if I made major changes during one of the prior passes.  It also helps, when deadlines permit, to let some time pass between initial writing and one of the editing passes.  This helps you look at it with fresh eyes.

  1. c.    Get Help

When possible, I try to have another person read over what I wrote, for technical accuracy, and grammar and style.  For instance, I had my lovely wife read over an early draft of this article.  When I am writing something technical, I am always inclined to ask what was confusing or unclear as that indicates a section that probably needs more editing.  Of course, in situations like a writing contest, it might be against the rules to have someone else assist.  But outside of that narrow scenario, having someone read over your writing can be useful.

  1. IV.          What to Write

Finally, I think it is worth looking at what to write.  When I write about SQL Server or most other technical topics, I am normally writing the article I wish I had been able to find a couple weeks before.  Most of my topics come from situations where I faced a technical challenge for the first time, but could not find a good reference on how to deal with it.  So, I would normally piece together a solution through a combination of references that dealt with something close to what I was trying to do, poring over the manuals, and banging my head against the problem until I found something that worked, even if it wasn’t elegant.  Then, if I thought it might be something others would also face, I might write it up.

Although that type of article comes from a problem I already solved, the writing process has always taught me something I didn’t know.  At a minimum, writing about it cements the knowledge in my mind and helps me clarify my own understanding by forcing me to explain it.  Sometimes, I am actively surprised by things I find while fact-checking or doing additional testing for an article before submitting it.  Before I wrote the article about SQLite and SQL Server performance I did not realize that under some circumstances a clustered index can improve insert performance by avoiding IAM/PFS lookups.

Sometimes I decide to write because I think it is an excellent way to learn about a subject that I know little about and I find my topic through curiosity.  I decided to write about Undocumented Extended and Stored Procedures precisely because I knew little about them at the time and the writing process gave me a method to explore them and organize my research.

Occasionally, I will write something because someone asked a question, either directly to me or on a general forum, which got me thinking about the topic.  I wrote a general article on database performance because there was a small flurry of generic questions about performance on ask.sqlservercentral.com and I found myself writing similar answers repeatedly.

Generally, there are a variety of ways to find things to write about.  I find it most productive to focus on topics which will be appealing to decent niche of the SQL Server using audience, but most importantly topics that interest me.

  1. V.           Improving

As with many endeavors in life, the best way to improve is to practice, with a feedback mechanism.  When practicing something like writing, you need to know what you could do better; otherwise you might simply make the same mistakes next time without really improving.  The simplest way is just to wait a while and read over what you wrote with a critical eye and think about what you could have done better.  That is like reviewing your own games of Go or Chess to improve your playing.  It will definitely help, but only so much.

It is even more beneficial to get outside feedback.  One way is to publish and see what responses you get.  But of course, most of the responses will be targeted at your content rather than your style.  To improve on style, it helps to have another person review it specifically for style and give you detailed feedback.  Of course, it is nice if that other person is an experienced editor or writer themselves, but anyone vaguely in your target audience can tell you what sounded good and what didn’t.  They can point out what flowed well and parts where it was confusing or hard to read.

Reading can also help improve your writing.  Hopefully, reading about writing is useful.  But more specifically, it is good to read things that have a style you like, while actually focusing on the style.  See what they did that you liked so you can emulate that technique in your own writing.  I have frequently read good essays twice, once for the content and a second time to see how they wrote it.

  1. VI.          Conclusion

As with most things I write, I learned a fair bit in the process of writing this.  I think one of the most significant things I have found is the value of editing and rewriting.  Hopefully it will also be useful to others.

Additional References:

C.S. Lewis on Writing by C.S. Lewis

The Age of the Essay by Paul Graham

Writing, Briefly by Paul Graham

Writing and Speaking by Paul Graham

So You Want My Job: Freelance Writer  By Brett and Kate McKay (interview with Edward Mitchell)

The write stuff by Marvin Olasky

Writing, part deux by Marvin Olasky