
Ask HN: Advice on Recording Technical Screencasts for Non Technical People? - zemptime
Recently my team invested a lot of time into a large refactor. This took a while and &#x27;refactor&#x27; was a dirty word at upper levels in the org for some time. However, now it&#x27;s done, been out in prod, and it&#x27;s producing some seriously amazing results.<p>(The amount of time it used to take for engineering to do a couple kinds of <i>things</i> has been totally wiped away)<p>My manager (and his) requested I get together a screencast walking through what the refactor was, and what it&#x27;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.<p>Usually like to have resources to fall back on for tasks that refresh me on the fundamentals. Don&#x27;t have this for &quot;remember to do these things when communicating up many levels in the org&quot; as well as &quot;remember to do this when breaking down technical subjects for non-technical folks.&quot;<p>What&#x27;s important to remember and focus on, here? Any good resources around this?
======
codegeek
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
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.

