How should I communicate technical changes to a non-technical manager?

Question

I maintain software A, B, C and database D and E. Database D and E are used internally by software A, B and C.

I am often get asked by my manager to put xyz functionality in software A/B/C. She does not have any clue how can this be done. That usually requires

• Adding field to the database
• adding, modifying stored procedures
• Changes in the .NET application (actual application)

I am not sure how to communicate these changes to my manager in an effective way.

For example do I

1. Send email, it is done and describe a brief description of the new functionality + anything else that I did on my behalf as enhancement?

2. Describe the main items in the task as bullets and mark them Done next to it. This would usually be 3 items.

3. Write a detail of of everything thing that I did to complete the task, example

   1. created abc field in database D
   2. Change stored procedure xyz
   3. added stored procedure def
   4. change the default year in dropdown z to 2012
   5. Changed styling of dropdownlist on page B
   6. Change values of dropbox from 1,2,3 to Jan, Feb, March ..
   7. modified code on customerservice.asp which now uses the new stored procedure
   8. Link to page 123 added in CM.asp
   9. New function added which calculates the value for functionality M.
   10. redundant variable j deleted
   11. Admin2 permission added to page jkl
   12. title of the page changed from this to this
   13. Error is now being reported when uploading
   14. successful upload is marked by green, errors by red
   15. Link ABC moved fro top left and place next to the product field
   16. A new utility was created which does the comparison, .... (I did this on my own)

The problem with approach 3 is that it can be quite time consuming + is it justifiable to write all that just say, the functionality is done? Is it efficient use of time?

One of my previous manager used to break down the project in these little tasks so a 1 month project would come up with about 40 tasks.

My goal is to communicate the work has been completed, and in an informative and professional way. How much detail do I include?

Note: My manager is non-IT person but she is expert on business logic and has a good know how of the application and the database.

Answer 1

So, I would say all of the approaches you mentioned can absolutely work. I would just sit down with your manager and ask which form she wants. Depending on what she needs from you in terms of communication she will probably just choose one of the methods as the form she would like to see for most things that you work on. From there, she will ask for increased or decreased detail depending on the situation, and as trust builds over time (the more things you implement that go well), she will probably ask for less detail, generally speaking.

I think the fact that you've taken the time to formalize several different possible communications mechanisms is great. The reality, however, is that everyone is a little different in terms of the kind and amount of information they need or want, so it's really going to be a case-by-case basis. And always in business it's a good idea to ask questions and verify your understanding of what's expected, so there are fewer questions or gaps in what people are actually expecting of your work, and what you think they're expecting.

I wouldn't worry too much about the "show my work" aspect. Unless your manager is a micro-manager (and wants to know every little thing you're doing, which is possible - some people work this way), then so long as you deliver on what you promise to deliver, everything else tends to fall into place.

Finally, it is sometimes the tendency of highly technical people to try to compensate for a lack of technical knowledge in others by providing more technical detail and sending along a list of jargon and other details (I'm not saying that you're doing that here, this is just an expansion on my answer). Sometimes this method works, but more often than not what non-technical people really care about is the business value, the function, and how a particular tool or technical solution is going to fit into a workflow, produce more value for teams or customers, and ultimately the justification for why the technical solution is being implemented in the first place. Ask about that kind of thing, and make sure you're providing not just enough information, but the kind of information your manager/clients/customers are looking for: the goal of this kind of communication is both (a) that they understand that you're acting as a technical expert on their side, in their best interests, and (b) that they understand how the technical solution is going to ultimately help them solve the problems that caused them to seek a solution in the first place.

Answer 2

First - be clear on why you need to communicate this to the boss. I can think of three reasons I typically have this conversation with people above or below me:

• What's it going to take to do this? The before we start conversation. It's the chance for the boss to say "not worth it" or "go forth you have my blessing" - they need to know enough in their terms to get a sense of what the group/company is in for when you start. This can be time to complete, operational impacts, resources involved, or other changes in state that might be unexpected. Also - are there any risks - stuff that might go wrong? can we avoid/prevent it?

• Where are we now? In the moment, where are we with respect to the original chat about what it was going to take and any subsequent conversations. Is the work going faster or slower than originally expected? Is there anything new that will impact the outside world? I've never seen a technical project that went totally as planned - so knowing the unplanned stuff ASAP is important.

• What just happened? - When the change is done, what can the boss expect? If the boss knows the business logic, explain it that way - what's going to function differently? Also, is there any follow up work? Testing? Deployment? Future features that would be good for the to-do list?

Any major feature should be described. Often small cleanup work can be bundled all together and described as one thing.

I usually aim to strike a middle ground - I start with the major point with very little detail, and make myself available for more questions. Over time, I listen for the questions that are asked, and use that as input to building my next report. Chances are, a pattern will develop and you'll be able to see that the boss always asks questions in a certain direction -- probably a key area of concern for the business.

Detail level is a tough trick - different people appreciate different levels of insight. Because information overload is prevelant, I often try to err on the side of terse - particularly if the recipient is highly placed in the organization.

Answer 3

If you only provide a summary of what you did in terms of a requested feature "done/not-done list", your manager might not appreciate the scope and complexity of the tasks that were requested. Your manager needs to understand, for instance, that a "simple" feature request like "Can we just add a checkbox to this form" could require multiple changes across multiple tiers and will require testing, validation and deployment.

The problem of how exactly to communicate these tasks depends, as normalocity indicated, on what the manager wants or is capable of handling. In any case, somewhere you need to keep track of what you did for each request. If not for your manager, for yourself and other developers.

I would strongly recommend that a manager with direct-reports who are developers should be proficient in the usage of bug/issue-tracking applications. Email disperses information too much and makes it hard to figure out what is going on when there are multiple issues. Moreover, an issue-tracker provides a historical record that can be used to answer the question "what did developer-x do this week/month/year ?" (valuable for performance evaluations).

Answer 4

You need to analyze the current and future needs of your audience(s). Your manager is one consumer of this information; another is the person who may have to update your code in six months; another is a future manager/lead who needs to understand the state of the system.

What tools do you have available? From comments it seems you have no bug-tracking system; are you in a position to change that? A bug that anybody in the future can go read is more general than email to your manager, and it gives you one place to record all the discussion (if there was discussion). Do you use source control? If so, the check-in comments are an appropriate place for all the details that might be important later, while sparing you from reiterating what the diff reports automatically. If there's no source control, is there a meaningful change log? (Per-file, per-module, per-product... you'll need to determine the right granularity, based on change rate and audience.)

You should discuss this with your manager as @normalocity suggested. Understanding your manager's current needs is important. But you should also consider the other future consumers of this information and try to come up with a write-once scheme that satisfies as many of those needs as possible. What usually works for my groups is: discussion/rationale in the bug, implementation details in the check-in message, cross-links between the two.

I have no citations to offer, only personal experience. I've been in the software-development industry for many years at small and large companies, and I've helped non-developers (like interaction designers, linguists, user-doc writers, etc) advance from sending email saying "I put my new files on (file share)". Since you're a developer you're probably already fluent in the tools, so it's just a matter of putting them together in the way that meets your organization's needs.