5 Intersects of Content Strategy and Project Management (Part 2)

Developing the work focus and/or the work plan during development also proves to be common ground for both the project manager and the content strategist.

  • The project manager analyzes the requirements and the available resources and delivers a work breakdown structure or work package. That deliverable can be a set of stories for a two-week sprint or a full-blown Gantt chart.
  • The content strategist performs a similar analysis. But she must also consider how existing content and communication channels match with user wants and needs, as revealed by the audience and task analysis that she performed in the early stages of the project. The deliverables from this effort might also vary in form and format.

Note: This blog is the second in a five-part series that examines how the elements of the content strategist role both parallel and intersect those of the project manager’s role. See part 1 published in March 2019.

To help focus the work and the work plan, both roles consider the future state and perform a gap analysis, particularly if the customer deliverable is a new version of an existing product.

The primary tools that a content strategist will use to perform this gap analysis are a content inventory and a content audit. Both serve to help scope the work by answering the question “what is missing?” and both serve as a reference during development.

What is the difference?

Content Audit vs Content Inventory

Ann Rockley and Charles Cooper in their seminal book Managing Enterprise Content: A Unified Content Strategy distinguish a content inventory from a content audit by telling us that a content audit is the “process of actually looking at the content and assessing its value and opportunities for reuse.” In other words, a content audit is qualitative in nature.

On the other hand, the content inventory is, according to Kristina Halverson and Melissa Rauch, more quantitative in that it provides “just the facts,” focusing more on listing content and its use and or location. (Their book Content Strategy for the Web is one of my favorites.)

Choosing one over the other might be driven by time and/or resources. CMS, LMS, and database tools can help in assembling a content inventory, and often the resulting list can be pulled into a spreadsheet.

Then fact-based decisions can be made about what to keep and what to add to meet the parameters of the project and the audience needs. If customer deliverable and audience(s) are similar enough to a previous deliverable, perhaps the inventory and some straight-forward gap-filling are all that is needed.

I’ve leveraged such spreadsheets myself to accomplish such goals as planning web navigation and deciding where a new, small set of task topics best fit in the overall scheme of content deliverables.

Benefits of a Content Audit

A more qualitative approach to content analysis would have to be more specifically focused, but might yield more useful results. All of the experts I’ve encountered suggest taking a representative sample and then applying a course of assessments to what you’ve gathered: alignment with best practices, strategic fit, and/or reusability. Then apply the findings to the greater content set.

(Content reuse is a big topic, and I bow to other experts in the field, such as the folks at CIDM, for their guidance in a later evolution of this blog.)

Note that assessing content for its alignment to best practices should include an agreed-upon rubric. How does your team describe quality content?

You might want to start with Ahava Liebtag’s Step-by-Step Checklist, and adapt as needed – especially if your deliverables include more than text-based content. Another good resource is Sarah O’Keefe’s “hierarchy of content needs,” which she has described in a recent TechComm article (see the article Understanding Content Strategy as a Specialized Form of Management Consulting). Remember to consider the customer experience with the content, too.

Whichever path you take in a qualitative audit, I promise you the effort will be worthwhile – even quantifiably so! According to strategist Carrie Hane Dennison, as quoted by Halverson and Rauch,

…for every 5 hours spent performing a content audit near the beginning of a project, 20 hours can be saved during later stages, preventing costly project delays.

Carrie Hane Dennison

Content audits can also lead to creative problem-solving. I’ve recently leveraged the results of a set of rolling content audits I performed to propose a new approach to a specific content type, setting our content (and my team) up to grow in a strategic direction while meeting the needs of a new audience.

Application to Work Planning

The gap analysis – defined in terms of opportunities to meet new or evolving audience/user needs – helps the both project manager and the content strategist decide to do next. Fill the gaps, of course.

In the world of content development, especially when it engages sophisticated tools like a CMS and DITA, a content strategist and development team have lots to consider:

  1. What type of content is best to meet the audience’s needs? (DITA gives us the archetypes of task, concept, and reference).
  2. What level of detail is needed?
  3. How best can the content be conveyed to the audience (table, illustration, video, help file, FAQ, chatbot, etc.)?
  4. How should differences among audiences be accommodated?
  5. How should the content be categorized? And how should metadata applied?
  6. How does the content leverage or expand existing infrastructure? For example, an existing information model? An existing reuse strategy?

Not all of this has to be decided up front. Content development is as much discovery as development. But what should be decided up front is how the development team – content developers and product developers – work together.  

How a content strategist applies the outcome of a content inventory or content audit will vary by project. Often, the breadth of the project and the level of engagement with product development – and with learning deliverables development – will influence that initial project planning piece.

My team, in the midst of tackling content to support a major release and a new audience, has chosen, for example, to leverage a modified Kanban approach. We use an Agile-friendly tool that allows content strategy inputs and analysis to be recorded in “spike” stories within a larger “epic” that contains multiple work “stories” or issues.

Note that prioritization of content development can be part of this planning, too, but often evolves through later stages of development.

The next blog in this series will address validating the work plan and refining a content-planning calendar.

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.