Ghostwriting — the art of writing for someone else

One of the new projects I’ve taken on is ghostwriting ‘blog articles for one of my clients. While I have plenty of technical writing experience — where I take a topic or application that isn’t mine and try to write about it — ghostwriting is an entirely new experience for me. Not only is it something new for me to tackle, I’m finding the experience to be interesting, and even fun!

My client maintains a ‘blog as part of his website, and by his own admission, isn’t a prolific writer — which is where I (along with one or two others) come in. I’ve only done a couple of articles for my client so far, but I’m learning a few things as I go along.

  • Keep in mind that it isn’t your article. One thing I need to remember is that even though I’m the one doing the writing, I’m not the one doing the “writing.” Essentially, I’m taking someone else’s thoughts and putting them into an article. (Sounds a lot like technical writing, no?) While I’m putting these thoughts and ideas into words, they are not my thoughts. The intellectual property belongs to my client, not me. As such, I consider the article as being my client’s property.

    I recognize that this can be a potentially slippery slope; by that same token, it could be argued that technical writing could belong to the subject matter expert (SME), not the person writing the documentation. I won’t talk about that here; first, this goes beyond my expertise (maybe someone who knows more about intellectual property law than I do can address this better than I can), and second, this discussion goes beyond the scope of this article.

    As far as I’m concerned, the client has the final say about the article. It’s possible that my client might give me credit for writing it, but that’s up to him. I’m just taking his thoughts and putting them into words.

    Speaking of writing someone else’s thoughts…
  • Writing what someone else is thinking is hard to do! Most people understand how difficult it is to understand another person’s thoughts; after all, that’s what communication is all about. I’m sure most communication professionals are familiar with the Shannon-Weaver communication model. For the benefit of those who aren’t, here’s a quick synopsis: a sender sends a message to a receiver. However, noise breaks down the transmission (note: the noise may not be literally “noise”), so when the receiver receives the message, it is never 100% accurate (and it never will be; the noise is always there. It’s like a mathematical graph; the line approaches, but will never reach, 100%). The receiver sends feedback to the sender (during feedback, the sender and receiver roles are reversed — the feedback becomes the new message), who uses it to adjust the message, and the cycle begins again.

    That communication model becomes magnified when ghostwriting an article because what the receiver — in this case, the ghostwriter — is feeding back to the sender is much, much more precise. A ghostwriter is trying to write on behalf of the client, and the client wants to make sure that what is being written is (1) accurate, and (2) maintains a voice that the client likes. In all likelihood, the client and the ghostwriter will go through several iterations of edits and adjustments.

    This reminds me of another thought…
  • I fully expect that what I write will be changed. Never get too attached to anything that you’re ghostwriting. Any time that I ghostwrite a work, I fully expect it to be different by the time my client and I are finished with it. As adjustments are made between me and my client, what we end up producing may look completely different from what I originally wrote.
  • You’re writing for someone else — but still be yourself. Even though I’m writing someone else’s thoughts, I never think about whether or not my writing “sounds” like the person for whom I’m writing. Thinking about writing in another person’s voice stifles my work and is a huge distraction that destroys my productivity. I write whatever comes naturally to me, and only through the editing process do I start worrying about the article’s voice, when the client starts adjusting the article to his or her liking.

    This thought brings to mind a quote from one of my favorite movies.

“No thinking – that comes later. You must write your first draft with your heart. You rewrite with your head. The first key to writing is… to write, not to think!”

William Forrester (played by Sean Connery), Finding Forrester
  • I’m learning new things! I’ve written before that one of the best ways to learn something is to write about it. Any time that you write about a topic, you end up learning about that topic — sometimes to the point of becoming an SME! Ghostwriting is no different. As I’m writing for my client, I’m learning new things and gaining new perspectives that hadn’t previously occurred to me.
  • I’m gaining new writing experience. I think this might be one of the biggest benefits of ghostwriting. Not only am I gaining additional writing experience, I’m also learning how to do so from another person’s viewpoint. As I mention above, I’m learning new things. I’m also learning how to be a better communicator, as it sharpens my communication skills as I continually feed back with my client. And it also teaches me how to look at things from a different point of view, which is what ghostwriting forces me to do.

I’m discovering that ghostwriting is a rewarding experience. It’s a great way to gain writing experience, and it ultimately makes me a better writer, a better worker, and a better person.

Comment your damn code!!!

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
— Martin Fowler

When I was a computer science major in college, I had professors who used to dock points if my code wasn’t documented.  It didn’t matter how well-written my code was, and it didn’t matter how well my code worked.  If I didn’t include comments to describe my code, what my variables were, why I used certain functions and coding techniques, a project that could’ve gotten an A grade instead got a B.

That memory came back to me this evening at our SQL user group meeting this evening.  Our guest speaker was Jen McCown, who gave a presentation called “T-SQL’s Hidden Support Feature.”  (A description of her sessions can be found here, and I found a SQL Saturday link to it here.)  Her presentation talked about a feature included with T-SQL (and just about every language imaginable).  It is guaranteed to improve how people handle, develop, and maintain code, and it costs nearly nothing to implement.

What is this miracle feature, you ask?

Code comments.

Simply commenting code can save developers lots of headaches and development time.  It can provide an explanation of how and why code snippets were used.  It can describe variables, what they’re for, and how they’re utilized.  It can describe program structures that help in debugging and maintenance.  I even remember a comment to a SSC forum post by Jeff Moden who mentioned the return on investment of commenting code.  It also reminded me of Steve Jones’ article about how important it is to comment code.  I believe Jen’s presentation should be required for anyone who writes code.  The benefits for commenting code are endless.

Commenting code is probably one of the simplest and most useful, yet most underutilized, methods of documentation.  I’ve mentioned time and again about how documentation gets no respect in technology, and yet too many developers still refuse to do it.  Jen’s presentation was a reminder of how important it is to document code; in fact, she also mentioned some points that didn’t occur to me.  For example, documents such as Word, Wikis, or Confluence can get lost, misplaced, or buried.  Code comments, however, stay with the code; it cannot get lost or separated from the code.  (There were several other points she mentioned as well, but it’s her presentation, not mine, so I don’t want to take away from it.)

When I was in school, I was docked points when I didn’t comment my code.  Sometimes, I think developers should be docked pay if they don’t do so.  Commenting code is the simplest, yet most effective tools around.  So you want to be a better developer?  Then comment your damn code!

To paper, or not to paper?

After trying to implement updates to one of my documents.  I realized that I was having problems trying to visualize how to incorporate a number of needed changes.  After staring at my document on the screen for a period of time, I decided to print out my table of contents to better visualize the document structure.  The table of contents serves as a de facto document outline, enabling me to get an idea of the document’s structure.

However, the mere fact that I had to print out the table of contents got me thinking: is paper still relevant in this digital age?

These days, it seems like everything is digitized.  An increasingly number of people are reading books on e-readers and tablets.  Even I, a longtime New York Times reader, stopped buying hardcopy newspapers a long time ago and started maintaining a digital subscription.

That said, there’s something to be said about savoring a good book — a real book, with paper pages to flip, and a dog-eared cover.  Even though I maintain a digital Times subscription, every once in a blue moon, I’ll pick up an actual newspaper and sit myself down in a comfortable chair in a Starbucks, flipping through the pages and getting my fingers dirty with newspaper ink, while enjoying a cup of mocha.

(I’ll also confess to being a little biased, since my wife works in the newspaper industry.)

While viewing documents entirely on a screen seems to be the way of the world these days, I’m finding that there are some instances where there is no substitute for paper.  For starters, I recently wrote that, as a tech writer, I sometimes come across mental blocks in my work.  Viewing a document as a hardcopy, as opposed to on a screen, sometimes helps to break the stalemate.  With paper, I can take whatever individual sheets I need, place them on a table, and skip through whatever I need to edit.  I am able to better visualize document structure and hierarchy so I can better understand where things need to go.  I also have the advantage of being able to pick up a pen and scribble any notes wherever I need them and wherever I please.  Try doing that on a computer screen.

Paper copies could also help alleviate eye strain.  (I am not an expert in this, so for all I know, I might be off-base here.)  I sometimes find it easier to look at material in print than I do on a screen.  I say this, despite the fact that the old tube-style CRT monitors have gone the way of the dinosaur.

By no means am I advocating that we should go out and kill more trees; on the contrary, I am all for taking steps to protect the environment.  All I am saying is that paper is not completely dead.  Although most documentation these days is digitized, I believe that the imminent demise of paper is somewhat exaggerated.

Technical writer’s block

“What no wife of a writer can ever understand is that a writer is working when he’s staring out of the window.”
— Burton Rascoe

“Waiting for the break of day; searching for something to say; flashing lights against the sky; giving up, I close my eyes…”
— Chicago, “25 or 6 to 4”

Those of you who write creatively — whether it’s a book, an article, music, etc. — have all experienced writer’s block.  Even if you don’t write, maybe you’ve experienced it in some form.  Maybe you were assigned a writing project in school.  Maybe you’re trying to come up with ideas for a party or how to celebrate a co-worker’s special occasion.  It even comes up when my wife and I discuss what to do about dinner (“What do you want?”  “I don’t know!  What do you want?”).  No matter what form it takes, the moment when your brain fails to come up with any ideas (sometimes called a “brain cramp”) happens to all of us at some time or another and more often than we’ll admit.  As much as I’d like to post a ‘blog article each day, there’s a reason why I don’t.  A lot of it is because I don’t necessarily write articles professionally and I don’t always have the time to do it, but an equal part of the reason is not being able to think of things to write about.

For this article, I’d like to talk about technical writer’s block — yes, there is such a thing, and it happens more often than you think.  (I don’t know if that’s a widespread term; for all I know, I might have just coined a new phrase.)  However, it differs from other forms of writer’s block in that a technical writer already has a subject about which he or she is writing.  In this case, it’s not a matter of what you’re writing about; it’s more a question of how to write about it.  I can’t tell you how many times I’ve stared at a computer screen for (at least) twenty minutes, only to realize that I spent those twenty minutes just blankly staring at the screen.

Those of you who are technical writers, let’s see a show of hands: how many of you have been given, say, a step-by-step instruction to write about, but have agonized about how to put it together?  Should you list them as numbered instructions?  Should you keep it to simple bullet points?  Is it better to put items into a table and write out definitions for the terms?  People who know nothing about technical writing don’t understand the struggle; they think it’s just a matter of throwing it together and making numbered points from them.  What they don’t realize is that it is not that simple.

For one thing, writing instructions isn’t that much different than writing code.  Both involve logic.  But let’s say you have an instruction to “push the red button” but only if you performed another step or are faced with a specific circumstance.  In structured programming, this would probably take the form of an IF-THEN or CASE statement.  But when you’re writing a document, situational instructions aren’t as clear cut.  There is no standardized method for writing an if-then statement in a step-by-step document.  I’ve seen this situation addressed in different ways; in one job where I was employed as a full-time technical writer, the group include a style with their template that included a small table for these situations: do this for one situation, do that for another.  I’ve seen others where a step is accompanied by a note: “this only applies to (whatever).”  Since there is no standard way to address this, it likely makes writing instructions more, not less, difficult than writing code.

Your audience likely plays a role.  I’ve espoused time and again that you need to know the audience for which you’re writing.  In my first successful technical writing project, I made sure that I put myself in the reader’s shoes, empathizing with the reader.  “How do I write this so I can see what I need to do?”  That strategy made things very clear, and I was able to write a good document.  Unfortunately, tech writers don’t always have this luxury; sometimes, either the type of audience is unclear, or the writer is writing for multiple audiences.  If you know your audience, it gives you an idea as to how to structure and write your document.

As I wrote earlier, design matters.  Of all my experiences with technical writer’s block, this is probably the one with which I struggle the most.  How should things be laid out that would most help the reader?  Where should things be placed so that they best direct an end user?  A document’s design often makes or breaks a successful document.

I just wrote about some of the issues I face.  How to resolve them is not as clear cut, and I don’t have as many answers as to how to address them (that might be worth its own article).  Here are a few ways that I’ve dealt with technical writer’s block.

  • Ask questions.  Clarification helps answer some of the issues with which I have to deal.
  • Get help.  Another set of eyes can sometimes break the impasse.
  • Work on something else.  Working on another task can sometimes spur ideas.
  • Walk away.  Sometimes, you just need to take a break.

I’m sure there are others ways as well that haven’t occurred to me.  How do you deal with technical writer’s block?  Feel free to respond in the comments.

Agnostic document references

Many of you who are technical writers — or data professionals — understand how important it is to not expose real data.  There is a huge emphasis on data security, as there should be.  But a lot of people never think about smaller pieces of data within a document — something as simple as, say, an email address.  In a lot of documentation I write, I make it a point to make much of it as anonymous and agnostic as possible.  There are a number of reasons for this, as I outline below.

I’ll start with a point of emphasis that I make in documentation time and again: know your audience.  Earlier this year, I was responsible for writing a user guide for an application that was to be used by multiple clients.  When I first started working on the document, the application was only being used by one client.  The application — and the document — contained many references to that one client.  In order to update the application to serve multiple clients, all references to the one client had to be removed, not just in the application itself but also in the documentation.  If a document is to be used by multiple audiences, specific client references should be made generic.

Likewise, I’ve accessed applications that display my name on the screen: “Welcome, Ray Kim,” for example.  If I screen-capture that image, I often alter the image so that my name is removed.  I don’t know about you, but I wouldn’t want to be contacted incessantly about an application that I probably know little about.

Another reason is data security, which becomes a larger issue by the day.  Sensitive corporate data risks being exposed within documentation.  For example, for my screen captures and illustrations, I request a “dummy” account that displays “bogus” corporate data for document illustration purposes.  I’ve gotten into the habit where I request this for every document I write.  Corporate data is sensitive; indeed, there is an increasing awareness of keeping such data private (the European Union’s GDPR and laws such as HIPAA and various other data protection laws come to mind).  Live data should never be used in documentation (unless authorized by the client in question); you can never tell what can be revealed in that data.

Here’s another reason I have for keeping documentation generic.  Let’s say, for example, an instruction for additional help directs you to “contact john.smith@yourcompany.com” in your document.  However, there’s one problem: John Smith no longer works for the company.  The correct contact is john.public@yourcompany.com.  But nobody made you aware of this change, nor is anyone aware that this contact is in the documentation.  And who is to say that John Public won’t leave the company or change roles in the next couple of weeks?  Additionally, listing a specific person runs the risk of that person getting spammed by peope who decide to use the contact for reasons other than the one listed in the document.  These risks come up any time a document references a specific person.  A better approach is to reference something more generic — say, a generic mailbox (e.g. HelpDesk@yourcompany.com) or a departmental site.

Here’s another argument for using generic references: how often does the document need to be updated?  Let’s say, for example, you write a document that references “Acme Corporation.”  Over the course of time, “Acme Corporation” changes — perhaps the company is bought or merged, the name changes, and so on.  How often do you need to go through your document looking for “Acme Corporation” and all its variations (shortened to “Acme,” abbreviated as “AC,” misspellings, etc.)?  And suppose your document is hundreds of pages long, with company references interspersed all throughout the document?  Making those edits does not make for a good working day.

Documentation runs the risk of exposing large amounts of data.  For data security, privacy, or even simple editing reasons (and maybe a bunch of others that I haven’t thought about yet), unless there’s a specific reason for not doing so, illustrations, examples, and references should often be made generic.  It’s a simple but critical step that can make your job better as a technical writer, and save your organization from a number of headaches — possibly ranging from complaints from audience members to a lawsuit.

It was the best of times, it was the worst of times

Steve Jones recently asked: what were your best days at work, and what was your worst?  He also issued a challenge to write about our typical days at work.  In terms of writing about a typical workday, I have the first of four (per Steve’s challenge instructions) draft articles warming up in the bullpen; hopefully, I’ll crank that one out sometime within the next week or so.  But in the meantime, for this article, I want to take a moment to address the best and worst days.

In terms of the worst day, I don’t think there is any contest.  I think it’s pretty safe to say that 9/11 was my worst day at work.  (For the benefit of those of you who don’t feel like clicking my article link, I worked for a company that had an office in the World Trade Center — when 9/11 happened.)

In terms of the best days, however, that requires a little more thought.  It’s not that I haven’t had any great days — that isn’t true — it’s just that there are a number of them, and having been a working professional for (cough! cough!!!) years, trying to pick out a few that stand out over the years is difficult for me to do.  So what I’ll do is pick out a few project victories that I’ve had over the course of my career.  Granted, I’m picking these from the top of my head, and there very well might be others that were more significant that I’m not remembering right now, but for purposes of this exercise, I’ll write about some projects with which I was involved and take a measure of pride.

I’ll start with a project related to the worst day that I mentioned above.  One of my tasks was to maintain an inventory of the servers in our data centers.  For a long time, this was a tediously manual task.  I went through our data centers with a clipboard, checking to see what servers were in each rack, noting any changes and adding new servers and racks that I found.  I drew a map of each room in Visio, even going as far as to count the floor tiles so that I could draw them to scale.  I populated the maps with boxes representing server racks and came up with a naming scheme directly tied into a row-and-column location scheme, making it possible to identify and label each rack so they’d be easy to find.  Included with the maps was a listing of servers within each rack.  I maintained the Visio file on my PC, making sure it was backed up to a departmental file server, and keeping hardcopies in each server room as a reference for various IT workers.

Because this was a manual process, the maps were never completely accurate — I have no doubt that new servers were continually added in-between map updates — and it was a tedious process.  All the while, I kept thinking, “there has to be a better way to do this.”  Sure enough, I found one!

I discovered that all our servers included a product called Insight Manager.  Among other things, it included the ability to collect server BIOS information and store it in a format suitable for importing into a database such as SQL Server.  Using the Insight Manager data structure as a template, I set up a SQL Server database on one of our departmental servers and created a system that enabled it to import data from any server on demand through Insight Manager.  I now had a central database with server data that could be updated at any given time!

Of course, data isn’t information unless it can be interpreted and understood, so the next step was to create an interface for it.  I was responsible for maintaining a departmental intranet site; although it was an internal intranet, I treated it as though it was a full-blown web site.  I created a web site to display the server data stored in my back-end.  I took my Visio server room maps and created image files from them.  From the image files, I created image maps that enabled a user to click a server rack on the map, drilling down to a list of servers in that rack.  Clicking on a server displayed data for that server — serial numbers, IP addresses, applications, and so on.

My server inventory system, which I previously had to update manually, was now automated!

This project was a major milestone for my career.  It was my first significant foray into SQL Server.  (At that time, I hadn’t yet learned about data normalization; had I known about it, I could’ve made the back-end even better.)  It gave me some experience with image maps, HTML, and classic ASP (the technology used on that intranet server at that time).  Most of all, it was my first taste of what it was like to be a web applications developer.

Memories of this project also reminded me of another good day I had on the job.  One particular day, I traveled to remote offices in Yorktown Heights and Middletown to survey their data centers for the server inventory system that I just described.  I hopped into my truck (I owned a small Toyota pickup truck at the time) and drove to Yorktown.  It was a gorgeous picture-perfect day; the sun was out and it was comfortably warm with low humidity.  It was comfortable enough that I left the air conditioner turned off and drove the entire trip with my windows rolled all the way down.  It was the kind of day where I wished I owned a convertible!  My route between the Yorktown and Middletown offices took me through the Bear Mountain area, including traversing the Hudson River over the Bear Mountain Bridge.  If you’ve never driven through that area of New York State, it is an absolutely picturesque and beautiful drive.  The entire trip was so fun and relaxing that it did not feel like a business trip at all; I actually felt as though I was on a vacation!

Finally, I want to talk about one last project in which I had a hand.  In one of my first jobs out of college (my second job out of school, actually), I was responsible for supporting my company’s document imaging system at a client site (a client that eventually ended up hiring me directly).  One of the system’s components was a WORM optical platter jukebox that was in constant use and occasionally needed operations maintenance, which ranged from simple tasks such as inserting an optical platter to complex ones such as restarting it when it locked up.  The device had to be operational 24/7, even at hours when we were not in the office.

I was tasked with putting together a small set of instructions — nothing big, just a few pages — that explained how to perform these tasks, including the correct way to insert a platter, what to do when (unfortunately, not if) the machine stopped working, and so on.  It needed to be written in such a way that the night maintenance staff could maintain the device.  So I sat down in front of my PC with a blank MS Word file and said to myself, “if I was a member of the night staff, what would I want to read that would enable me to perform these tasks?”

I had intended for the document to be a simple three to four page quick reference.  As I wrote and came up with more ideas that would help the readers who would be using it (including the innovative — for me — use of illustrations), the document kept getting bigger and bigger.  I don’t remember how big it eventually became, but I think it was somewhere in the ballpark of thirty pages.  I had absolutely zero technical writing experience at the time; I wrote the document completely by instinct.  I didn’t really know what I was doing; I just did things (illustrations, headers, subject organizations, etc.) that made sense to me.

The final product was a huge success — so much so, in fact, that management developed a training program based around this document.

A couple of years later, I discovered that nearby Rensselaer Polytechnic Institute had a Masters degree program in technical communication (note: I am not entirely sure if the program still exists).  I had been interested in pursuing a graduate degree, and I thought the program sounded interesting, so I decided to apply.  During my application interview with the faculty, I brought along a copy of that operational jukebox document I’d written.  I explained that I’d written the document completely by instinct and with no knowledge or experience in technical writing whatsoever.  The faculty seemed to be impressed with my effort on that project.

I was accepted into the program.  I now have an MS from RPI hanging on my home office wall and listed on my resume.

This article ended up being a lot longer than I expected.  Looking back on this exercise that Steve assigned, I suppose my good days at work were more significant than I thought.  These projects were major events that ended up shaping this professional career.  I suppose the moral of the story is not to underestimate job achievements.  You never know where they might lead!

Don’t keep an idea to yourself

My friend Greg Moore recently commented on a Facebook post regarding our upcoming SQL Saturday (tomorrow!) in which he credited me for my idea about a forum about women in technology.  The idea had occurred to me when I saw that Rochester SQL Saturday was doing such a forum, and I suggested that we should do one as well.  To be honest, I’d forgotten that I’d made the suggestion until I saw Greg’s comment earlier this week.

It just goes to show that you never know where an idea might lead.  I made a simple suggestion about an idea I’d seen about a forum discussion.  Tomorrow, it’s going to become reality.

For whatever reason, it made me think about the following meme.

Image result for sharknado meme

So the moral of the story: if you have an idea, don’t keep it to yourself.  You never know where it might lead.

The document development life cycle

A recent work request reminded me of production life cycles.  I got an email regarding a user guide for an application that I had written earlier this year.  She said she was looking for something similar.  She asked me how long it would take.  I told her that I would need to look at the application, but I also said there were a number of things to consider, including how much access I could have to the application so I could test and document it, who would be available to answer any questions I had, who would be able to test and review the document, the document format, and so on.  (On hindsight, I also realized that I’d forgotten to ask a very important question: who is the audience?)

The conversation reminded me about the importance of the document development life cycle.  In an earlier article, I talked about a number of issues that frustrate people who understand technical communication and documentation.  This is another frustration that is poorly understood and widely ignored.

I’ve had the privilege of having worked in both software development and professional document development environments.  Many people fail to understand that there is no difference in the production process between the two environments.  To put it another way, the development life cycle between the two is no different!!!  The software development life cycle (SDLC) is widely known and an industry-standard term.  But if you’re not a technical writer or communicator, when was the last time you heard any mention of a document development life cycle?  For that matter, are you even aware that such a thing exists?

It seems to me that most people aren’t.  How many of you have been frustrated when you’re given a documentation project, whether it’s an application, a process, or a product, and been told that it needs to be finished in a couple of days (or even a couple of hours)?  This is completely disrespectful to technical writers, and it upsets me to no end.

An example of a software development life cycle
(source: SoftwareTestingMaterial.com)

Like software, producing good documentation follows a life cycle.  Here’s a sampling of what takes place when developing a document.  Document requirements must be defined: what is being documented, what is the scope, and so on.  And let’s also not forget what may very well be the most important requirement: who is the target audience?  The document must be designed and written.  This involves organization, layout, and design.  Writing it is no small task; I’ve written before about how hard it is to interpret ideas that come from a subject matter expert (SME).  Once a document draft is written, it needs to be reviewed (“tested”) by an SME for accuracy; are the ideas conveyed in the document correct?  Adjustments to the document will likely need to be made, and it will need to go back to the technical writer for editing and updates.  Document format needs to be considered; will it be deployed as a PDF document, or will it be stored and maintained in an online format, such as a Wiki, Sharepoint, or Confluence?  Speaking of maintenance, bear in mind that if the application or process is changed, the document will likely need to be changed as well.

Documentation is a critical, yet overlooked and disrespected, profession in technology.  A technical writer cannot be expected to produce a quality document in mere hours.  As with all quality products, documentation also follows a life cycle.  Whenever the document life cycle is properly followed, the result is a quality document, which, in turn, results in satisfied customers and a positive reputation for your organization.

Want to learn about a topic? Try writing about it

Every now and then, I’ll peruse the forums on SSC.  In addition to people answering questions about SQL Server, there also tends to be some banter, which is probably not unusual in many forums of this nature.  One of the comments I’ve seen time and again is something like, “I learn more about subjects by answering people’s comments on these forums.”

There is more truth to this statement than people realize.  In my experience in writing about technology, I often find that I end up learning about the technology about which I’m writing — sometimes to the point of becoming a subject matter expert.

Several years ago, I taught part-time at a local business school (roughly equivalent to community college level).  I taught primarily general mathematics and a few computer classes.  I was once asked to fill in for another instructor who taught statistics.  My problem: I didn’t know much about statistics.  So, I read up on it (along with the syllabus that I would be teaching that day).  I wanted to at least be able to sound like I knew what I was talking about.  As it turned out, by teaching that class, I actually learned something about it.  The students were not the only ones who got an education that day.

The other day, I began writing a draft article regarding a subject about which I’d like to learn more: BI (edit: the now-finished article can be seen here.).  I’ve dabbled in BI a little bit; I worked a previous job where I was asked to perform some data analysis (which is how I learned about cubes and pivot tables), and I took a course in decision-support systems in grad school.  I’m seeing more SQL Saturday presentations about BI; indeed, there are even SQL Saturday conferences dedicated to BI topics (usually indicated by the words “BI Edition”).  It is a topic about which I do have some interest, and it’s something about which I’d like to learn more.

My friend, Paresh Motiwala, who was one of the organizers for SQL Saturday Boston BI Edition a while back, encouraged me to apply to speak at the event.  I said to him at the time, “the only thing I know about BI is how to spell it!”  (His response: “Hey, you know how to spell SQL!”)  On hindsight, I probably should have applied; it turns out that even BI Edition conferences accept professional development topics, under which nearly all of my presentations (so far) are categorized.

So if I claim to know so little about BI, why did I decide to start writing about it?  Well, I’m trying to learn about it, and I’d like to pass along what I learn.  But, I want to place a greater emphasis on the first part of that statement: I’m trying to learn about it.  Writing about it makes me learn something about it a little more in-depth.  And by doing so, I discover that I have a better grasp of the topic.

Hopefully, relatively soon, you’ll see an article from me about BI.  Hopefully, I’ll have learned enough writing about it that you’ll be able to learn something from me.  And hopefully, I’ll have demonstrated that I’m learning something new, and improving myself in the process.

If you want to learn something new, try teaching it or writing about it.  You’ll be surprised how much you, yourself, learn in the process.

Better Comments

This is a reblog of a post by my friend, Steve Jones. I’ve often said that commenting code is a form of documentation, and needs to be done more.

Voice of the DBA

I assume most of your comment your code.

Well, you probably comment code most of the time.

I’d bet your comments have quite a bit of detail.

And you do this completely inconsistently.

That’s what I’d think, or maybe just what I want. Even the best developers I know will not consistently comment code. You can drift through any project on Github and see this. Those projects on GitHub might even be better documented because people know they are public. In most corporate environments I have worked in, I’ll find that when people get busy, or distracted, or even when they’re experimenting to find a solution, and they don’t write detailed comments. Usually only when someone fixes a bug, with a solution found quickly, do I get a really useful comment.

There are all sorts of ways that people think about commenting their code. I ran across a post from…

View original post 254 more words