7 Definitions of Content Strategy (in 16 Years)

If you don’t know what content strategy is…well, you have good company in the majority of my friends. Below are some definitions of content strategy that I have collected or borrowed from the collections of others. Hopefully, they will help you and my supportive but confused friends understand better what I do for a living.

“[Content strategy is] A repeatable method of identifying all content requirements up front, creating consistently structured content for reuse, managing that content in a definitive source, and assembling content on demand to meet your customers’ needs.” – Ann Rockley in Managing Enterprise Content: A Unified Content Strategy (New Riders, 2003).

“Content strategy is the practice of planning for the creation, delivery, and governance of useful, usable content” – The 2009 Content Strategy Consortium.

“’Content is story. And content strategy is storytelling’…In this model, the content strategist figures out how best to tell the story: what assets are present, what do they need to prescribe, how should they be arranged, and how should they be updated or maintained?” – Margot Bloomstein in Content Strategy at Work (Elsevier, 2012).

“Content strategy is a system that consists of a repeatable process that governs the management of the content throughout the entire content lifecycle.” – Rahel Anne Bailie in “A Methodology for Content Strategy,” Intercom (Society for Technical Communication), May 2013.

“But content strategy is more than that. It’s about envisioning the future of content – its development, management, and delivery – and creating a plan that helps us leverage content to achieve its goals. It’s about creating a flexible, responsive roadmap that can be quickly adapted to the challenges that will undoubtedly interfere with our well-intentioned plans for success.” – Scot Abel in “The Importance of Vision in Content Strategy,” Intercom (Society for Technical Communication), May 2013.

“A content strategy establishes how an organization will leverage its content assets to achieve its overall business goals. A content strategy also provides a roadmap describing how these goals will be realized.” – Joe Gollner in “The Technology Side of a Content Strategy,” Intercom (Society for Technical Communication), May 2013.

“…I would add: content strategy is what guides content teams to best processes for each stage of the content cycle.” – Monica Bussolati in “10 Definitions of Content Strategy” (blog, Sept. 2017)

I have placed these in chronological order to better appreciate the evolution of the discipline of content strategy since Rockley (with Pamela Kostur and Steve Manning) wrote her seminal book. I see goal-driven planning, roadmap creation, repeatable process, and governance as common concepts across these definitions and across the years. What do you see? How do these definitions align with your experiences?

Documenting a Hardware API: The Challenges

In last month’s blog, I summarized some introductory concepts and tools for writing about hardware-related REST APIs, a journey I started myself a little over a year ago. To be honest, though, I didn’t make that journey alone. I have been the content strategist for a group of writers, who came at the challenge from various backgrounds.

As such I understand some – but not all – of the sticking points for some writers from some backgrounds. So I am curious, what other challenges do you or your team face when writing about a system-level or hardware-level REST API?

One example of a challenge that we faced as a team – documenting a REST API written by two geographically separate software development teams – was adhering to a consistent and common terminology for common concepts. And this was true of the developers, too, as they developed data types and parameters for the API.

I was amazed, as an example, how many different terms we in the high-tech world have for describing the capacity of a storage drive (be it HDD or SSD)…disk space, drive space, drive space allocation, storage space, storage allocation, repository, storage repository…and well, you get the idea. Difficult enough for one person (sigh, that would be me, the content strategist) to keep track of, let alone whole teams of people.

Let me know what kinds of challenges your team faces in your REST API journey. I will summarize them here in this blog space in a couple of weeks. I am happy to do so with or without mentioning names or companies.

Comment on this blog or send me an email at debra@dkconsultingcolorado.com. Looking forward to hearing from you!

8 REST API Documentation Tips for Hardware Writers

Introduction:  I re-joined Oracle as a technical writer and content strategist in a storage systems development group over two years ago. In mid-2017, our team recognized the need to expand our content about a system’s evolving REST API. Like many veterans of hardware documentation, I didn’t know much about APIs, RESTful or otherwise. So I embarked on a journey to learn more.

This blog, written originally near the beginning of that journey (for a class) and updated since, presents helpful links and guidelines about REST APIs for former hardware technical writers like me.

Technology services based on the representational state transfer (REST) architecture or a RESTful application programming interface (API) are becoming more important for hardware developers and content developers to understand. Wait, what? Why do I have to understand programming stuff?

Well, I hate to break it to you, but programming isn’t just for coders any more. APIs in general – and REST APIs in particular – play an increasingly central role in the burgeoning cloud services market as well as the Internet of Things (IoT), according to Jennifer Riggins and others.

Because APIs provide a “level of abstraction” beyond the uniqueness of the “thing” itself, they enable a connectedness and interconnectedness that we mere humans have not seen from our refrigerators and vacuums before. For a perspective, review Alexandra Bowen’s still-relevant 2016 SlideShare set, and memorize her first answer to the question – Why APIs? “APIs provide the ability to glue and integrate services.”

REST API Concepts

Before you start to panic, remember that a REST API is based on the target’s “resources” – that is, the elements of the hardware itself as well as the data that journeys to and from that hardware:  disk drives, temperature sensors, network connections, user account data, and so on. These are concepts most of you are already familiar with.

Also remember that actual “programming” doesn’t really occur within the REST architecture. Activity is limited to configuring, retrieving, changing, or removing the target’s resources. These activities are controlled by the four main HTTP methods – GET, POST, PUT, and DELETE – which are common across most REST APIs. (For a description of the HTTP methods, refer to the RestAPITutorial page on the topic.)

If you need to get further acquainted or re-acquainted with REST concepts and terminology, review the Pearson eCollege tutorial on YouTube. And yes, for those of you who love Wikipedia, it offers a pretty good overview, too.

Guidelines for Documentation

Development of REST API content has become more standardized in recent years. Writers can assume a certain amount of experience and knowledge on the part of the audience, especially developers. Consumers of REST API documentation, in turn, expect to see content that meets them at their level. They may even expect the content to be organized in a certain manner or contain certain topics.

So as with any documentation project, start with understanding the REST API’s audience. To gather some tips about audiences, read Diana Lakatos’ blog “The Ten Essentials for Good API Documentation.”

Next, use the following eight guidelines to plan and organize your REST API content:

  1. Create a short Getting Started section that contains the following:
    1. The format for a fully qualified URI, including the base URL
    2. Authentication instructions
  2. Describe any unique request headers or unique use of request headers, or anything else unique about the API, including special query parameters.
  3. Include an alphabetical list of resources for easy reference.
  4. Provide details about each resource and endpoint; if need be, group the resources into logical categories for better management of the details.
  5. Provide lots of example requests and, as needed, example responses. Developers love code examples!
  6. Ensure that all your code examples appear in the programming language most often used by the target audience (for example, JSON).
  7. Include a list of status (HTTP) codes.
  8. Provide guidance for error-handling, as needed.

Going Further with REST API Documentation

For more tips on how best to document a REST API, review the 2016 SlideShare set from Marta Rauch of Oracle Corporation and read Diana Lakatos’ second blog “Ten Extras for Great API Documentation.”

Many RESTful API gurus point to Twilio’s REST API guide as a model for good API content. However, I prefer Twitter’s approach, which I find easier to navigate. For an example of hardware-specific documentation, see Oracle’s guide to the RESTful API for its ZFS Storage Appliance (written by a team other than mine).

Finally, as for which tools to use when you document your product’s REST API, almost any good documentation tool will suffice. That said, there is a growing trend among professionals to intertwine REST API development and documentation by using tools like Swagger – now associated with the OpenAPI Specification or OAS (refer to http://swagger.io/).

For some tips on how to evaluate REST API documentation tools, read the Algolia blog “Good API Documentation Is Not about Choosing the Right Tool.” For a review of available tools, read the article “Best Practices and Tools for Documenting APIs” by Mark Boyd of ProgrammableWeb, a news and information website dedicated to APIs.

Now you know as much or more than I did when I started my journey. Good luck to you!

Note: Mention of products or companies in this blog does not constitute an endorsement of those products or companies by me.

4 Rules for Business Email – Rule #3

Is it too late to wish you all a Happy New Year?

OK. It’s been a while. There, I’ve said it. I started another writing gig in late December, and I have been remiss about updating this blog. And I am sorry. On the plus side, I get lots of opportunity these days to put my own words of wisdom into practice. (But, obviously, I am not above punning….)

So – Ahem – to review, here are my four rules for writing professional, business-like emails:

  1. Be Polite
  2. Be Professional
  3. Be Clear
  4. Follow up! (which is an outcome, really, of the first three)

Before the holidays, I got through the first two, so I’ll focus this blog on the third – Be Clear!

Waterford Gifts, Lismore Crystal Bowl 6"

Clarity in emails, like clarity in crystal-ware, is a balance of ingredients. Lead crystal, also known as “flint glass,” is made up of silica and lead; traditionally, in fact, it was 24% lead oxide (which gives flint glass its refractive qualities but is not so good for the human nervous system). Lead crystal is still beautiful to look at. Waterford’s lead crystal chandeliers glitter ever on in Westminster Abby, and Waterford lead-crystal panels comprise the famous New Year’s Eve Ball in Times Square (see how I snuck that in there!). Lead-free crystal is also a balancing act, with various alternative oxides (potassium, zinc or barium) replacing the lead oxide.

Clarity in business emails comes from balancing straight-forwardness (for lack of a better word) with brevity – with a little bit of good organization and audience sensitivity thrown in. In fact, a straight-forward organization of your email is a good place to start. Always start with your ask and/or an introduction to your attachment. That is, lead (pronounce it “leed” in this sentence!) with your question or request or – if you are responding to another email – lead with your response and/or a brief phrase/sentence that describes your attachment.

Recently, a friend of mine was awkwardly caught up in a job-referral situation in which she wanted to ask a complete stranger for a job interview, having been referred to that stranger by a manager who had rejected her job application at his company (though he did so with great heart and positive feedback). She asked me to look at her email, which opened with a long complex sentence about her job qualifications. (For an example of a long, complex sentence, look at the first sentence in this paragraph!) She followed that with her question, requesting an interview.

I advised her to start the email with her question (since the email from the mutual acquaintance was attached anyway) and to follow that question with two sentences created from the overly complex sentence she had originally started with. Wallah! She secured the job interview and went on to win the job. Hurray! OK, her success probably can’t be solely attributed to her revised email. But I like to think I helped.

If your opening sentence (with your question/request or response/attachment-description) needs more context, then go ahead and provide it – but in a separate paragraph. You can even label that paragraph with the heading “Background,” “Clarification” or “Additional Information.” Here’s where audience sensitivity comes in. Most of the time, your reader will be interested only in (and read no further than) your ask or response. However, sometimes if – like me – they are overwhelmed with email and might have no clue what you are talking about, they need to understand the circumstances that compelled you to write the email. This is particularly true if you are rejecting a proposal or idea.

The idea here is avoid leaving the reader to guess about what you mean (“What the…?”) – or to guess about where you stand. Give him/her another sentence or three (depending on the situation) that provides some context for your opening phrase/sentence. Keep it brief, but be sensitive.

Example: How about lunch on Friday? I have news to share!

Response: Can we push to Monday? Have a big project due 1pm Friday.

While this simple exchange would have been fine minus the second sentences in each, the expanded versions let each recipient know that the relationship valued (well, relatively speaking). Plus it sets up at least two topics of conversation for the ensuing lunch.

Which brings me to the fact that I am very hungry. OK, too much information – including too much information in an email – is never a good thing. So always circle back to the previous rules – be polite and, above all, be professional. No need for my email pals to know that my stomach is grumbling. I’ll spare them (but not you!) that detail.

Before I go on to my dinner (and sipping wine from a crystal decanter!), I’ll remind you that I have one more business email rule to define – Follow up!

4 Rules for Business Email – Rule #2

As a memory jog, here again are my 4 rules (guidelines) of business email etiquette:

  1. Be Polite
  2. Be Professional
  3. Be Clear
  4. Follow up! (which is an outcome, really, of the first three)

When I wrote about the first rule of business email – Be Polite – I suggested that you avoid email wars by requesting use of a different communication channel (phone call, face-to-face meeting, facilitated meeting, water pistols at midnight, whatever). But if you absolutely, have to respond by email, please, please remember that you are responding to a human being, not a machine. Most human beings these days – at least the ones I know – are doing the best they can while facing tremendous personal and/or professional challenges. So please remember that.

And if you can’t remember that (really? It’s so hard?), then remember that nasty-grams can live forever on someone’s hard disk drive. So be neutral, be sensitive, be smart and above all, be professional.

And that is our second rule of business email – Be Professional.

Email gurus Silberman and Johnson both remind us to watch the tone of our emails. Tone is a tricky thing. But believe it or not, it’s easier to moderate the tone of a written communication than it is sometimes to moderate the tone of our voice. (You can test this next time your cube neighbor douses you with a water pistol – how high and loud is your voice as you supposedly laugh it off?)

To moderate the tone of your emails, choose neutral words in place of more highly charged words. For example, refer to “status,” “open issues,” and “concerns,” not “debacles,” “problems,” or “mistakes.” While you might consider a shifting deadline to be an “issue,” it’s probably better not to refer to it as “missed” or “failed,” unless those words are used officially by your company or are generated by a software application – and you have your attorney sitting right next to you (holding a water pistol). People do take these labels personally, and you don’t want wade into an inter-departmental (or inter-company) conflict unnecessarily.


Pushing into controversy myself a bit here (cue toe-in-water image), I’ll say that part of being professional is being sensitive to the person who was concerned enough about a topic to actually send you an email, especially if that someone is lower on the food chain than you. Being tough or clever or “above the fray” doesn’t always win the day; being appreciative and helpful can have more lasting effects (and remember, the email sender might not always be lower on the food chain).

(Note that I am not going to use the American idiom about catching flies with honey here, because, well, it’s gross and, besides, I’ve already used the term “food chain.”)

You know this, because you know it’s true in “real life,” too. I was reminded of this recently when I attended an evening public meeting in my community. Four professionals had formed a panel discussion on a specific topic. (I’ll be neutral here and not name the topic.) Toward the end of the evening, a woman in the audience stood up and asked specifically for help for her child. She was obviously emotional (though not overly so) but very sincere in her request. Not one of the panel members responded. Yes, you read that correctly, not even one.

Finally (to the relief of everyone), another professional in the audience stood up and offered to talk with her after the meeting. (At the same time, he acknowledged that he wasn’t sure that he was the best person to help her.)

How hard was that? Which one of the six people involved in this situation was the most professional, in your opinion?

OK, now I’ll take my toe out of the water, foot out of my mouth, water pistol away from my head, whatever, and talk about one last pet peeve about professionalism in business email. And that has to do with loooooooong email chains – the kind that cross weeks and even months on the calendar – or emails with multiple or hefty attachments. For the love of Mike, people, keep the context but ditch the heft! Mike, by the way, is the poor IT guy responsible for your company’s overtaxed email server.

So the last sub-rule is about professionalism when responding to a business email that’s been circulated through half the world: Be smart. Before you hit Reply All, make sure that all of the right people are on the distribution list; then delete and summarize any of the simple intervening replies (say “the following people on the distribution list have already agreed”; then list them) and keep the original email as close on the page to your response as possible. Believe me, people will thank you (including Mike).

And I will thank you to keep reading my blogs on email etiquette (smooth, eh?). Next topic is business email Rule #3 – Be Clear.

4 Rules for Business Email – Rule #1

Yes, email is still around, and it is still the main form of official communication between business professionals. I realize that rules on email etiquette have been around as long as email has. Email etiquette guru Lindsay Silberman (author of several Email… manuals) has 25 rules for you to follow, and Dave Johnson of MoneyWatch has 9 “keys” for your pocket. But I think I can easily boil those down a bit more.

To start, we should all make one giant assumption in our 21rst century lives: Nothing you send in email will ever die. (This is borrowed from AIIM’s mantra: Nothing on the Internet ever dies.) Emails can be copied, pasted, forwarded, saved and (Hello, NSA!) archived in large data centers somewhere. I am not saying that you should abandon your free-speech rights at the entrance to the corporate campus, just apply your good-sense filters and “look both ways” before you hit Send.

So really there is one overarching rule here: Don’t be stupid. Goes without saying that in the professional business world, you shouldn’t send obscene, rude, sexist, bigoted or otherwise offensive emails (nothing you wouldn’t want your grandmother or grandchild to see). So I think we can explore email etiquette by looking at only 4 rules – well, guidelines really:


  1. Be Polite
  2. Be Professional
  3. Be Clear
  4. Follow up! (which is an outcome, really, of the first three)

In this blog we’ll explore the first rule (guideline) and what it means – Rule One: Be Polite

Be Polite – I know this sounds as though I have turned in to my mother, and oddly, I found myself asking my 87-year-old mother the other night if she had been “polite” during a recent dinner at a neighbor’s home when she didn’t like the food. (The reasons why I asked this are deep and many, but I won’t overshare here.)

Translation to business email:  Respond politely to whatever is put in front of you, even if you don’t like it and, most especially, even if you don’t like the person who put it there. The key here is to respoooooond, even if you simply say, “Thank you for your email. I’m sorry, but I am swamped right now. I’ll respond by noon tomorrow.” In fact, you can even set this message as an automatic response (using your email tool’s out-of-office feature) on days when you need some uninterrupted time at your real job – say, planning your next pirate-ship takeover. It will buy you some work time now – and some think time later. (Please don’t overuse this tip. And please do what you have promised to do – and follow-up!)

The main idea here is to say something that indicates you received the email (and thus convey to the sender that the email is not lost in the ozone somewhere). So thank the communicator, and/or acknowledge the meeting or clarification, and/or respond to the request. It doesn’t take most of us long to type, “Got it! Thanks.” Or “Thanks. I’ll be there.” Or “Thanks. I’ll discuss this with the team, and get back to you on N-day.” (Where N=the day you follow-up. More on follow-up with Rule 4, topic of a future blog.)

If the email you’ve received is itself impolite or contains provocative or otherwise unpalatable notions, rather than start an email war with cannons blaring, use your email response to set up another communication channel. You can always write, “May we talk offline about this?” to set up anything from a hallway conversation to a conference call. Or – and here’s a unique idea – take the initiative and pick up the phone to call the sender. (If it makes you feel better, you can throw in a pirate’s “Aaaaargh” somewhere in the conversation…see if they notice.)

One last note: It goes without saying here (again!) that you don’t always have to respond to every email. For instance, you do not have to respond to automated emails, or all-hands emails, or a similar widely distributed email. Use your good judgment (or your mother’s good judgment, whichever best applies).

Next blog – Rule #2 – Be Professional

10 Commonly Misused Words


Well presented list here! Don’t be compelled to use the word “travesty!”

This is a reblog from “Written Rambles.”

By Tyler Vendetti

There are so many words in the English language that it’s not surprising that the definitions for some of them have gotten mixed up over the years. It’s possible that you’ve gone your entire life without realizing your mistakes. I’m sure people have noticed. One day, you were probably walking down the street, casually chatting with an old friend, and one of these words slipped out of your mouth. Before you can move on to your story about how Mufasa would actually make a very attractive human, your friend stops to correct your error, and suddenly, your whole life starts to feel like one giant lie. How long have you been using that word incorrectly, you wonder? How many angry Facebook rants have you ruined with your improper grammar? While I can’t give you an answer to those questions, I can at least provide you with a list of other tricky words so that you may never have to suffer from this embarrassment ever again:

1) Travesty

What you may think it means: a tragedy, an unfortunate event

What it actually means: a mockery; a parody

This one, I’ll admit, is my own personal error. For the longest time, I equated travesty with tragedy, mostly because in passing, they sound like the same word. It’s stupid, I know, but if you knew how many times I confused fetal position with beetle position, you wouldn’t be laughing. It’s a serious problem.

2) Ironic

What you may think it means: a funny coincidence

What it actually means: contrary to what you might expect

It’s not ironic that you bumped into a talking turtle in a sweater vest right after you told your friend how cool it would be to bump into a talking turtle in a sweater vest. It’s a coincidence, and believe it or not, those two words are not related. Also, you should probably lay off the drugs because I’m pretty sure animals shouldn’t be talking.

3) Peruse

What you may think it means: to skim or glance over something

What it actually means: to review something carefully/in-depth

How this definition got completely turned on its head, I’ll never know, but I’ll be sure never to say “I’m going to go peruse my math textbook” ever again, just in case someone overhears and tries to hold me to it under the real meaning.

4) Bemused

What you may think it means: amused

What it actually means: confused

Again, with the whole “words sounding alike” issue. I’m starting to think I just need hearing aids. This is getting out of hand.

5) Compelled

What you may think it means: to willingly do something, to feel like you need to do something

What it actually means: to be forced to do something (willingly or unwillingly)

The word you’re looking for is “impelled.” I agree, it doesn’t get enough attention.

6) Nauseous

What you may think it means: to feel sick

What it actually means: to cause nausea

When you eat too much ice cream and declare to your mom or the nearest adult, “I feel nauseous,” what you’re actually saying is that you are causing people around you to feel sick. Thanks, jerk. (For the record, “I’m nauseated” is the way to go.)

7) Conversate

What you may think it means: to hold a conversation

What it actually means: ABSOLUTELY NOTHING

This word is a mix of conversation and converse, and doesn’t actually exist, like unicorns or YOUR DREAMS. (I’m kidding. Unicorns are totally real.)

8) Redundant

What you may think it means: repetitive

What it actually means: superfluous, able to be cut out

“Including this sentence is redundant because you already mentioned your love of Santa Claus in the previous paragraph.” This has always been my exposure to the word redundant, so it only makes sense that I would think repetitive was correct. I can’t be the only one? Right? RIGHT?

9) Enormity

What you may think it means: enormousness

What it actually means: extreme evil

I don’t know where the “extreme evil” thing came from (probably the Devil) but enormity makes more sense as enormousness in my mind.

10) Terrific

What you may think it means: awesome, fantastic

What it actually means: causing terror

Okay, so “causing terror” is more of an outdated definition but I still thought it was interesting. Maybe keep this fun fact in the back of your mind the next time you call your favorite camper, “Terrific Tommy,” because technically, a few decades ago, that might have been an insult. Unless instead of a camper, he’s a serial killer. In that case, go for it.

Info via DailyWritingTips.com, Cracked.com, and WriteItSideways.comImage via GinnyTonkin.com.

Punctuation Rules for Blogging

Really appreciate this punctuation infographic from Darin L. Hammond, blogger for Steamfeed.

I think his comma rules need a bit more explanation, which I will provide in a later blog. And I disagree with one of his comments on parentheses (punctuation doesn’t always have to follow – unless it’s the end of the sentence as in this example). But, otherwise, this is pretty useful.

Of course, the challenge is that he assumes you already know what subject, verbs, clauses and prepositions are. Soooo let me know what your questions are!


Between you and me, ‘than’ can take it but not him

This silly phrase is actually meant to help you when using the two very different but often similarly misused words “between” and “than.”

No need to know that “between” is a preposition that can sometimes act as an adverb, and “than” is a conjunction that can sometimes act as a preposition. The most common mistakes with these words appear in the words that follow them – and the sometimes invisible words that don’t.

Okay, I probably shouldn’t be talking about invisible, spirit words now that we are a day past Halloween. But I didn’t get many trick-or-treaters at my house last night. So I am hopped up on mini candy bars today and still wondering about a mysterious knocking sound that woke me up early this morning.

So between you and me, I’m feeling a bit shaky…

And that, by the way, is the correct way to use “between.” Specifically, this word should be followed by nouns (“the lamppost”) and/or by pronouns in the objective case (me, us, him, her, them). Pronouns, are, of course, words that substitute for real nouns, but I’ll bet you knew that already. Objective pronouns are a specific category of pronouns that receive the action of a noun or follow a preposition – as in “I ate them all (“them” being a pronoun that refers to candy bars, which I ate).

We sometimes over-correct ourselves when using “between” because we believe it is prahpah English to say “between you and I.” Nope, it’s not. Go ahead and say me, mee, MEEE after the word “between.” It’s the right thing to do.

The same is not true when you use the word “than.” This is a word that disdains objective pronouns and prefers a diet of invisible words. Weird but true. You must use the subjective category of pronouns (I, we, he, she, they) after the word “than,” because it really expects more of you.

Yep, it’s just like your mother. The word “than” really expects to introduce an entire clause – subject + verb. But often we cut it short – just giving it the subject and leaving the verb (and whatever else might follow the verb) unsaid.

An example is “I am sleepier than he.” Really, you (and my mother) should assume I was going to say “I am sleeper than he is.” But I left off the “is.” The “is” is invisible but understood. (I could say something about a former president and the definition of “is” here, but I won’t. I’ll leave it unsaid.)

What really got me going on this was the jarring sentence I read the other day in an otherwise entertaining magical mystery novel. (Trying desperately to keep a theme here.) In the middle of a long descriptive paragraph, the author wrote “She was younger than him.” Nooooooo! Where was the editor? Where was her mother? How could this have happened?

But then I ate a mini candy bar – and felt better. Happy November!