Alignment: it’s critical to be aligned in so many ways. Aligned has many levels of complexity and its exact definition may change from company to company. But an overall definition of alignment might simply mean that everyone knows what they are doing, has access to the information they need to accomplish their tasks, and is synchronized with those to whom they must deliver or from whom they need information.
Recently, I was reminded of the importance of being aligned when a valued member of my client’s team spent hours reviewing the documentation. Some of his comments were relevant; but most were not because much of what he spent time writing about no longer exists in the documentation.
Without question, his comments were technically correct and expected, if you were to evaluate documentation for a release three months ago against today’s product. In a very polite email, he explained that he’d added some comments to the readme project that they chose as their documentation tool (probably the subject of a different post entirely).
As I tried to implement his comments into the help project, I realized something was terribly wrong. Sadly, comments in this readme application are not version-specific.
While I have been working in the current (and soon to be published version of the documentation), he had inadvertently landed in an outdated version that was supposed to be archived some weeks ago. The mistake? Mostly his. The frustration, shared by all.
It likely started because he was looking at the live version of the documentation but the cause here is less important than the outcome. A clear lack of alignment. Time wasted, nerves frayed. And a bit of embarrassment on all sides as I had to explain his mistake. Obviously upset, he correctly blamed the PM who should have updated the published version.
And then yesterday, that very same PM was annoyed with me because two weeks ago he told me I needed to balance the docs between the DEV environment and the PROD environment. Since he’d told me to use the DEV environment to document, this was a change in direction, but one that I embraced. I made sure that screen captures were taken from PROD; that any future features were marked as “unpublished”.
Until, that is, I realized that DEV and PROD were moving farther and farther apart. I was being told to document what was supposed to already be appearing in PROD, only it wasn’t. I continued with the sinking feeling that users were going to be terribly confused. After all, I wasn’t sure why I was seeing a gap in the product while the PM and others said the product was fine and it was the documentation that was falling behind.
This latest version included a very needed change. Gone was a confusing term that was replaced by a much better one. And behind the term was a workflow that had been very confusing. DEV was showing me a much streamlined process and the correct terminology. Except PROD was still showing the older workflow and term. The CEO was talking about updating the documentation; while I was getting nervous that I was moving the documentation too far ahead.
They couldn’t understand why I was hesitating; I couldn’t understand why they weren’t concerned about the gaps in the product. What the CEO and PM didn’t tell me was that last week, they created a new environment to meet the immediate interest of a potential client. I was looking at DEV and PROD; they were looking at DEV and the new environment.
The PM was annoyed when I questioned eliminating a term that was all over the documentation because it still existedhe clearly had outlined a path ahead. His manager was annoyed that I wasn’t moving forward to close the gap between the currently version and the docs. What they were both missing was that I had not been aligned with the dev team’s decision to radically change where the latest version of the product was being stored. Alignment.
Only when they took time to align, could we move forward. It’s a technical writing concept but also a life lesson.
I’d write more, but I now have to close a gap in the documentation and re-align reality. Would this have happened if we weren’t working from home? The sad but truthful answer is “probably not”.
In whatever counts as a normal world, I’d have walked down the hall and asked a developer, “Hey, what’s up with PROD?” or “We aren’t showing PROD to the new customer, are we?”
So, in these challenging times, one important piece of advice would be – stay aligned (and when you think you’re aligned, check to make sure you really are.
More, impress upon others the pitfalls that can occur when documentation and product/support/development aren’t aligned.