How cloud issues can trickle down to content development

Photo by Sebastian Herrmann on Unsplash

I regularly discuss with a colleague the state of the cloud and how to make cloud messages resonate with readers He’s a solutions architect. I’m a technical writer. We work in allied professions, but he sees things I don’t see. What I came to see after a few discussions with him is how corporate cloud issues have an even more direct effect on content than other topics I’ve written about during my career.

Here are three ways cloud issues can hurt content development:

1. Lack of cloud subject matter expertise

The cloud is such a fast-moving and evolving topic. I’m just not talking the latest Amazon Web Services (AWS). Google Cloud Platform (GCP) and Microsoft Azure. That news is only a part. There’s a plain lack of cloud expertise in organizations to support content development.

The cloud has its share of people who don’t belong. It happens with every major technology trend that hits the market. These are people grasping at the cloud to preserve their political stature. They can hijack the cloud message you need to communicate with your users/readers. Don’t fall for the PowerPoint slides go with people who have the right subject matter expertise in cloud topics.

My preferred subject matter experts for cloud content call themselves lifelong learners. If somebody doesn’t know something. That’s OK. We can figure it out together. There’s nothing worse than somebody BSing me they know something they don’t.

2. Constant cloud services and market evolution

The release velocity of AWS, GCP, and Azure blows past any other technology topics I’ve written about in the past ten years. It’s hard to keep up with the matter. I used to consider myself good at keeping up with technology. Now I find the cloud lapping me with the speed of new feature releases the startup ecosystem that’s sprouting up around the cloud contributes to the pace.

I’ve had the fortune to work with brilliant cloud people. By extension, I have contact with others through IDG TechTalk chats who range from the senior architect to the CxO level. They are people far smarter than me, and they each have challenges keeping up with new releases.

3. Business prevention disguised as change management

It’s no secret I’m no fan of organizational change management (OCM). Too many times I’ve seen OCM become business prevention. OCM should give business users the content and message they need to transition themselves into a cloud-first enterprise but unfortunately, they can bog users down in surveys and other feel-good strategies.

A better cloud change management strategy means:

  • Creating a direct channel with business users by elevating their representation in cloud content development decisions
  • Listening to the cloud pain points from the users themselves not through the filter of a change management team
  • Thinking in terms of frameworks, jumpstart guides, and other content that can enable your business users to start small in the cloud while feeling self-sufficient

Final thoughts

Writers developing technical content about the cloud have to drink from a firehose with or without the challenges I outline in this post. My advice to counter such challenges is to include your writer in early on your cloud projects.

My name is Will Kelly. I’m a technical writer and content strategist based in the Washington, DC area. I’ve written for corporations and technology publications about such topics as the cloud, DevOps, and enterprise mobility. Follow me on Twitter: @willkelly

Empathy and the technical writer

Photo by Shane Rounce on Unsplash

The longer I spend in the IT industry as a technical writer, the more I come to see my job is more about people than ever before. By that, I mean that the technology part is easy. The people part can be complex, so I try to lead with empathy in my role.

I work as an individual contributor, so I work across different teams and personalities to get my job done. Here are examples of how empathy can help you as a technical writer.

Knowing the motivations of senior technical staff

As a technical writer, I believe you have to understand the motivations of senior technical staff and management. It’s more than if the person supports your writing efforts. It’s about where the project fits into the person’s professional world. Is it in their area of technology interest? Are they all talk but deliver nothing? Do they only go to project meetings to appear busy? Is the project tied to the staff member’s personal or professional goals? Other questions abound depending on the corporate culture, project, team, and employees should come to mind.

The lesson is to know your audience just as if you’re writing technical content.

Learning the ebbs and flows of people’s schedules

I once wrote that the best advice I’ve gotten about technical writing comes from programmers and it remains true to this day. I like to work as an individual contributor in a technology organization. It’s been years since I worked on a writing team.

Working the ebbs and flows of other people’s schedules is about knowing the best time and place to get information from people. You also need to use their preferred medium in which to get information from people. For example, I like to write and review documents myself. It’s my preference. However, it’s a rarity in my experience to work with people who work that way. I’ve had to bend and mold my working style to accommodate whiteboard ideation sessions.

I’ve also learned to adjust to people’s schedule when needed to get information. Whether it means coming in early, online chat sessions at odd hours, and most anything in between I’ve had to do it in the past.

Starting with a blank page

Ever since I got my start as a technical writer way back when I never understood why some technical writers who wrote nothing themselves. I’ve found that if you can start a document at a blank page and write as much as you can on your own it’s a whole heck of a lot easier to get information and reviews out of subject matter experts and management.

Dealing with people who blow deadlines

During my time as a technical writer, I’ve worked in environments where deadlines were optional. People just blew past them. There was almost never any accountability either.

Dealing with people who consistently blow deadlines can be complex and tiresome at least for me. Here are some methods I’ve used in the past to deal with people who blow deadlines:

  • Minimize my dependency on them as much as possible for the project (not always workable)
  • Bring people the answer and let them tweak it.
  • Build in a buffer for their procrastination.
  • Acknowledge that blowing deadlines is just part of the culture.

Discovering people who are in over their heads

One of the loneliest times in my professional life as a technical writer is when I find somebody who doesn’t know what they are talking about and tries to talk their way around the topic without answering my questions. You’re wasting your time feeling sorry for these people. They think they have you fooled because you’re just a technical writer. My tactic in dealing with them is just trying to work around them. Nod your agreement with them then quickly and diplomatically move on.

The flip side of that person is somebody who openly admits they don’t know the answer to my question. Sometimes it just takes a little time in a room with a whiteboard for them to figure out their answer to the question.

Final thoughts

At its heart, technical writing is a people game. The more energy you put to working with people the better you will collaborate with your team. Empathy will also improve how you interview subject matter experts.

My name is Will Kelly. I’m a technical writer and content strategist based in the Washington, DC area. I’ve written for corporations and technology publications about such topics as cloud computing, DevOps, and enterprise mobility. Follow me on Twitter: @willkelly

5 things I believe about enterprise collaboration

Photo by Kaleidico on Unsplash

I follow enterprise collaboration both as a long time technical writer in the IT industry and as somebody who has written about collaboration platforms over the years for online publications.

It can be too easy to wreck collaboration in my mind. I’ve seen it many times happen during my career, giving me strong beliefs about collaborative cultures and technologies.

1. Collaboration takes at least 2

I’ve worked with people in the past who thought that collaboration was a coworker doing something for them. These people had a lot of dependencies on other team members. The team never seemed to depend on these sorts of people much.

It’s not to say you shouldn’t help your coworker. Working with this type of person made me remember my best collaborations. The common theme in those collaborations was a complementary exchange back and forth of information, input, and insights that benefited the project, team, and the collaborators themselves.

It’s not to say that non-technical people are at a disadvantage with collaboration inside technology organizations. They need to pony up from their own unique strengths.

In the past, I’ve said that collaboration can be transactional depending on the organizational culture. Take, for example, the time-strapped organization that’s not well organized. It’s easier to get help from somebody in such cultures if you can help them towards their project goals.

2. Collaboration platforms work for the team (not vice versa)

I’ve come across awful excuses for collaboration platforms and processes during my years as a technical writer. Sometimes, these collaboration tools were downright business prevention. Users kept using email for collaboration or resorted to sundry acts of Shadow IT to collaborate on files.

Microsoft SharePoint is a prime example where users sometimes have to work for the tool. Think of the times you’ve encountered sluggish performance, Draconian security policies, and poor user experience (UX) that added up to you and your team working around SharePoint to get your job done. No team should have to lose time due to SharePoint issues. For example, I can remember having to use my personal OneDrive account on a contract because of my client couldn’t get access to their SharePoint site for me as a contractor. There were other cases where I had to use my personal Dropbox to collaborate on files.

3. Collaboration at its best means a comfort zone

Looking at some of my best collaborations past and present, I see a comfort zone between coworkers and teams as integral to collaboration success. There needs to be a level of trust and respect amongst team members to make collaboration efforts fruitful.

Working a technical writer — an individual contributor at that — I have to find a comfort zone between me and the subject matter expert (SME) to get the information I need to write. Most often, this means writing a document draft using as many source materials as I can find. I then go to them to the SME to review the draft and patch any gaps.

For my article writing, it means having positive relationships with editors and PR people whom I’ve never met face-to-face or even over video chat. Such trust and a comfort zone come from responding to requests, clear and concise communications, and doing right by the article amongst other factors.

4. Collaboration is about culture before technology

I’ve written in the past about collaboration being about culture before technology. My recent writing about DevOps continues to drive home that point for me.

Full confession, I’m a total collaboration tool geek about SharePoint, Atlassian Confluence, Microsoft Teams, and other tools. Collaboration is a topic I miss writing about, yet I’m the first to admit that none of these technologies can fix a culture that isn’t collaborative.

5. Every employee needs to own collaboration

I often find that enterprises neglect that everybody needs to be an owner in collaborative environments. At a top-level, it means decentralizing the control of your internal collaboration sites to project teams. Major collaboration platforms have the rights settings that can enable you to open up privileges to users without harming overall compliance.

Managing collaboration platforms needs to become part of the team DNA and made easy so it works in the background. For example, a technical writer has a big role to play in SharePoint environments. They should know their document library. They can play that role at the team level. Business analysts can and should play a similar role. Project managers should be able to speak to their schedules and related project artifacts.

Final thoughts

The technologies and culture that power collaboration still fascinates me to this day. I’ve seen so many enterprise collaboration initiatives tank over my career. The initiatives I saw become successful were most often grassroots happening at the project team level.

My name is Will Kelly. I’m a technical writer and content strategist based in the Washington, DC area. I’ve written for corporations and technology publications about such topics as cloud computing, DevOps, and enterprise mobility. Follow me on Twitter: @willkelly

5 lessons I’ve learned from coaching writing

Photo by Markus Spiske on Unsplash

My work as a technical writer sometimes means that I have to coach solutions architects and other technical people in the fine arts of writing. It’s a part of my work that I’ve come to find a new appreciation for over the past few years.

Here are some lessons I’ve learned:

1. Technical people hate to write, but there are reasons why

There’s a stereotype that technical people can’t write, and there’s much truth to that statement. I’ve had the fortune to work with some technical people who can write and write well. When I’ve brought up the roots of their writing hate, more than one person pointed back to some negative high school or college experience with a teacher. Another frequent response was being too busy.

2. Keep it simple for the non-writer

My rule for coaching a non-writer is to keep it simple for them. Figuring out just how to keep things simple for the non-writer happens on a case-by-case basis for me at least. Here’s a sampling of some things I’ve done in the past:

  • Encourage the non-writer to focus on being methodical and to break down what they are writing about on a whiteboard or on a piece of scratch paper
  • Encourage the logical thinking side of the technical person because of the role it plays in writing technical content
  • Tell them that the semicolon isn’t their friend so use Short paragraphs and sentences to improve clarity in their writing
  • Ask them what they need from me to be successful in writing the document and adjust my coaching approach with them

3. Encourage the non-writer to iterate on writing

I always advise anybody I coach writing to iterate upon what they write and sit on their drafts at least a day before they revise them if they have the time. It’s something I do as a writer, and I often relate my own experience with using this practice myself.

Depending on the person, I also encourage them to write a draft without editing until the draft is complete.

4. Introduce the non-writer to machine editing

Self-editing for non-writers takes time and practice for non-writers in my experience. I’m always happy to recommend machine editing tools to these people. HemingwayApp — which highlights lengthy and verbose sentences — and also Grammarly to non-writers I’m working with on a project. While these apps and others like them can’t replace a human editor, they can help serve as another set of checks for a non-writer who might not yet be confident in their writing skills.

I use that fact that AI is underlying today’s machine editing tools to make it more attractive to non-writers who’d benefit from the technology.

5. Deliver constructive and actionable reviews of what they write

It’s hard to not write in the IT industry and not have some bad experiences with document reviewers and editors. My aim is always to deliver constructive and actionable reviews of documents from non-writers that add value to their document and them.

It’s important to be seen as a collaborator, not as their freshman comp teacher. Part of this collaboration comes from being conversant in technology the document is supposed to cover. You can instantly lose credibility as a writing coach when you try to mold writing to fit your lack of understanding. You gain credibility when you write constructive comments with intelligent questions.

Final thoughts

While I dare say that writing does bring me joy in many circumstances, the same can’t be said for technical staff. I’ve made it my mission as a coach to offer the people I’m helping a positive experience with writing.

I’m a technical writer and content development manager living and working in Northern Virginia. Over my career, I’ve written bylined articles for ITSearchOperations, DevOps Agenda, Mobile Business Insights, CNET TechRepublic, and others. My areas of interest include cloud computing, DevOps, enterprise mobility, and collaboration tools. Follow me on Twitter: @willkelly.

5 types of people you interview as a technical writer

Photo by NeONBRAND on Unsplash

Long ago I came to see people as the greater challenge to my work as a technical writer more so than the technology I was writing about. It’s not that I don’t like people. I just came to see people in technology organizations

Here are the five types of people you interview as a technical writer (in no particular order):

1. The poseur

Over my career as a technical writer and freelance technology writer, I’ve had the opportunity to interview a lot of whip-smart people — some brilliant — and I’ve learned a lot from them over the years. I’ve grown fascinated by people’s “tells” especially the one type of interviewee I call the Poseur. Here are some of their characteristics:

  • Beats their chest about being a technologist
  • Abides by the rule that he who talks the most must be smart
  • Dismisses questions they can’t answer by changing the subject or lame excuses

Now mind you there’s more than one type of poseur. You might get lucky and find one who defers technical writer interviews to their employees politely. There’s no harm in these people — they can be great connectors — for technical writers. It’s the ones who lack self-actualization that can cause problems on content development projects as they become a blocker to success to save face and fight politically to prove their own relevance.

2. The old school geek/true believer

While so many folks fall for the mythos of snake people as the be all end all technology experts, give me an old-school geek with gray hair any day as a subject matter expert. I’m talking about the person who has been there, seen it, and done it.

While interviewing some old school geeks/true believers can mean having to put up some guard rails for the interview because they do have their war stories. Old school geeks are often the ones who respect technical writers with some domain knowledge about what they are writing about versus a generalist who’s not really vested in technology.

3. The product person

In my travels as a technical writer, I’ve come to see that there are just product people. They may hold the formal title of product manager, sometimes they might just be an accidental product manager — a product-focused person sometimes a developer — who has a vision for the product they are developing.

My favorite type of product person to interview is somebody who’s had a lot of customer contact and are very aware of the competitive landscape. These people can be a treat to me as a technical writer. I especially enjoy interviewing product people for articles I’m writing.

4. The services person

A services person understands the delivery side of the business versus the product. They may or may not be technologists by trade. I commonly encounter the services person in industries such as financial services, government, and telecommunications where security, compliance, and dare I say bureaucracy is the order of the day.

My favorite way to interview a person is in front of a whiteboard where they can break processes and procedures down while they are telling they are dropping some knowledge on me.

5. The evangelist

While I usually don’t see too many of what I call the evangelist when I wrote technical documentation, I do see them when I write articles, blog posts, and white papers. While I like interviewing the evangelist, it can always be a balancing act in my experience. You can encounter a poseur trying to impersonate an evangelist.

Interviewing an evangelist can be challenging. Some come into a media interview with a definite corporate line they want to push even if you are writing a vendor agnostic thought leadership piece. On the bright side, their enthusiasm can be contagious, and that can shine through in their interview answers.

In my experience, natural evangelists are few and far between, but you can cultivate evangelists. I saw that done when I was freelancing for CNET TechRepublic, I saw a corporate CEO go from a very rough interview to one of my go-to sources on a subject in about two years.

Final thoughts

While my passion for technology keeps me going as a technical writer — on the good and bad days — people also keep my interest in projects. It could be the people and personalities I work with on a daily basis or the people I interview for articles.

I’m a technical writer and content development manager living and working in Northern Virginia. Over my career, I’ve written bylined articles for ITSearchOperations, DevOps Agenda, Mobile Business Insights, CNET TechRepublic, and others. My areas of interest include cloud computing, DevOps, enterprise mobility, and collaboration tools. Follow me on Twitter: @willkelly.