Henry opened up a PDF on his laptop and went to page 27. The meeting continued around him as he scanned the text of the procedure he’d written 18 months before so he could verify some of the information that had been distributed.

“One way to look at this is that we want to prevent our customer from getting these phone calls all the time—or at all,” said Vanessa, the project manager. “What’s the first step?”

George, the business analyst, lifted a hand. “Well, since he keeps getting asked why people are or aren’t seeing this or that in the reports, I think it’s a data problem. We need to start there.”

“Or it’s a training problem,” said Melanie, the lead of the quality assurance team. She looked at Henry. “If there’s a data problem, maybe the users don’t understand how to set the data up correctly.”

“Which still makes it a data problem,” said George. “We need to identify what our software is currently doing with the data and how it feeds the reports. From there, we can determine whether the software meets all the needs and we just need to do better at educating the users. Or it’s possible that we left some things out of our data model. Maybe we didn’t understand as much as we thought we did a year and a half ago. The users may be trying to create relationships between objects in the system that we didn’t anticipate.”

“We did distribute a PDF when we released the software,” Henry added. “So we’ve told them how to set up the relationships between objects.” He glanced again at the text and then stared. Given the understanding he’d gained in the meantime, plus the content of the discussion, he found a couple of only partially true statements in the instructions.

He wondered if the problems that the customer was experiencing resulted from what amounted to inaccurate documentation.

And he didn’t want to speak up and suggest this to the group. Yet.

“Maybe what we need is more validation in the system,” said Nick, the development lead. “Documentation is fine only if the data stewards use it, and we don’t know if they are. If we put more validation in the system, then there’s less room for mistakes.”

“That would be some complex validation,” countered Theodore. He would know. Henry had had to document some of the data processes in another project where Theodore had been the database administrator, and he had done some amazing things with stored procedures and such. “It would be a lot of work to have the system analyze all the variables and give appropriate feedback. I think training is the key.”

“I think we’re getting ahead of ourselves,” Vanessa said. “Let’s start with George’s suggestion and identify what the software is doing. We need to show the customer the consequences of the relationships the users are setting up and find out how much of that is what’s supposed to happen. Who should do that?”

After some discussion, they settled on Henry as the person who would take the next step. He took the assignment to diagram the current effects of various object relationships in the system. “We’ll meet again on Thursday and use Henry’s diagram to guide our discussion. We’ll verify the accuracy, and then we’ll take it to the customer.”

As the meeting was breaking up, Henry asked George to come over. “I think these statements aren’t entirely true here.” He read them.

George’s eyes wandered as he thought about it. “I think you’re right.” They identified the correct phrasing, and Henry made a note.

“I wonder if this problem stems from this being wrong,” he said. “I could see how some of the problems the cusomer has seen could have happened because of this.”

“That may be the case,” George replied. “But I still think we’re missing something in our data model. If this procedure being wrong helped us realize that we missed something, then maybe it was a good thing.” He smiled briefly, perhaps a bit embarrassed himself. George had reviewed Henry’s documentation, so if it contained errors, it meant George had missed them too.

A little reassured, Henry returned to his desk and focused on the puzzle that was the data model.

Something like this has come up for me recently. The customer was receiving a lot of phone calls that boiled down to the same question. One phone call in particular became the proverbial last straw that spurred the customer to ask the program manager to look into the problem. In looking at my documentation, I found a couple of inaccuracies, and it’s possible that they were the direct cause of the data problem we ended up with. I haven’t verified this yet because at this point, it looks like it hardly matters (as long as I correct the inaccuracies). If my documentation led to the problem, it has led us to analyze a bigger problem that’s really at the heart of our customer’s difficulty.

The discussion has been about what needs to happen in our system vs. what is actually happening. We think the programming and the data model have fallen short in some ways; fortunately, the wiring can probably be fixed with relatively little pain. It’s a matter of making sure we know what the customer wants to happen so it will be programmed the right way.

However, it’s not just a programming problem. There’s also a communication problem to solve, and the first step was to portray our current system wiring in a way that the customer can understand and use to make decisions. I was given that assignment to put together this communication.

Stay tuned for Part 2, which will talk about the next stage.

Related entries (auto-generated):

Communication Problem or Programming Problem? (Part 2)

Communication Problem or Programming Problem? (Part 3)

Technical Communication: The QA of Product Design

Technical Communication Can Require Heavy Duty Hardware

Four More Reasons Your Company Needs Technical Communicators