Advice on Recording Technical Screencasts for Non Technical People?

Question

Recently my team invested a lot of time into a large refactor. This took a while and 'refactor' was a dirty word at upper levels in the org for some time. However, now it's done, been out in prod, and it's producing some seriously amazing results.(The amount of time it used to take for engineering to do a couple kinds of things has been totally wiped away)My manager (and his) requested I get together a screencast walking through what the refactor was, and what it's doing for us. They hold the sentiment that if other stakeholders basically left engineering alone for a while, more amazing things like this would happen, and want to use this as a major supporting fact in that narrative.Usually like to have resources to fall back on for tasks that refresh me on the fundamentals. Don't have this for "remember to do these things when communicating up many levels in the org" as well as "remember to do this when breaking down technical subjects for non-technical folks."What's important to remember and focus on, here? Any good resources around this?

codegeek · Accepted Answer

Focus on the results and not the technical details. I don't even know if a screencast of the code changes or refactor would be of any use. I would rather create a powerpoint with may be some code samples and focus only on results. For example, instead of saying "We took this monolithic function and broke it down into separate modular components which made it easier for devs" may not be enough. You should say something like "Doing xyz resulted in less bugs, faster developer turnaround times which resulted in more benefits being shipped to the end user. What we could do in 10 days before can now be done in 1 day due to this change". Stuff like that.
I would probably create a PPT with the following:
- Problems before the refactor
- results achieved due to refactor (e.g. more sales)
- How the refactor helped achieve those results
That's it. Simple and concise.

gt565k · Answer

You might want to consider brushing up on technical writing principles. You want to identify who the audience is, what their background is, and present content that's easy to absorb given their point of view.
You want to generalize technical specifics in layman's terms.
You said your refactor produced amazing results. Define those results using business KPIs or metrics that are quantifiable and portray your technical information in terms of those KPIs in order to speak to that audience.
I.e.
tech speak
We analyzed slow running queries that were composed of multiple views nesting within each other, resulting in bad query plans that degraded performance of our BI dashboard and increased downtime for our business analysts who could not get their job done efficiently.
Upper mgmt speak
We identified performance problems related to our BI dashboard, after root cause analysis and correction of those problems, our downtime has been reduced by 50% and business analysts can access the system without having to worry about overloading it at peak hours, producing better efficiency in their processes.
-----typically you want some KPIs or metric numbers in here to show quantifiable improvement over a time period) Whether you have those metrics historically or not, you could probably still extrapolate some meaningful metrics.
Now again, it depends on your audience. If you're presenting to technical leadership, maybe you do want to get into specifics at a technical level. Writing informational content is all about the audience, whether it is technical, medical, or otherwise topic specific.