Ask HN: Advice on Recording Technical Screencasts for Non Technical People?

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.

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.