This post is about making sure you get your message across by structuring your content correctly, and giving people convenient jump-off points when they’ve hit the level that is appropriate for them.
In my post about plain language, I mentioned a discussion on structuring content, and linked to a previous post called The Art of Miscommunication. I thought it was worth digging into content structure a little more.
We can think of the content structure as a pyramid. Starting at the top we keep things short and simple, then each layer down gets progressively more detailed. A person consuming the content can get to a level appropriate for them and stop, safe in the knowledge they have not missed something vital.
What do I need to know about this content?
- What is it about?
- Is it really meant for me?
- Are there any actions assigned to me?
- Is it even worth my time reading this, or have I been included for the hell of it?
If we think about emails, blog posts and videos, it’s important we understand what the content is about early. This allows us to decide if this is the right content for us. In my opinion this is about the subject of the email, or title of blogs and videos, along with a short first paragraph.
Using the example of an email, it might be important that some of the management chain understand a situation is happening, but they may not understand the detail of the issue, or have time to dig into it further.
Here is a silly example of an email subject and first paragraph, which represents how I think the top level of the pyramid should work.
“Payroll run failed. Will be fixed by this afternoon!
This morning’s payroll run failed. Jayne is on the case, diagnosed the problem and is confident it will be fixed by this afternoon. The P1 incident number is INC123456.”
It’s short! It tells me what I need to know. It gives me some confidence I don’t need to worry about things unless I hear different. At this point I might feel safe to jump out of the email. I know it’s a Priority 1 (P1) incident, which means it will have a wash-up meeting, so I don’t need to respond asking someone to document and communicate the root cause. I feel most higher-level managers should be happy with this, and be able to duck out now.
This is where we add a little more detail. We are still going to keep things short and simple. We will already have lost some of the readers, so the people left behind are here because they want something with a bit more depth. Maybe something like this.
“At 06:18 we got a notification to say the payroll process had died. It got escalated to Jayne, who checked the application logs. It looked like the payroll run had been hanging for a while and then died.
She asked the DBAs to check the database while she checked the OS layer on the app server. The DBAs said the database went really quiet at that time, like no new requests were coming through from the app layer, but didn’t think it was the database that was causing the problem.
Jayne noticed a Jenkins agent on the app server was grabbing 100% of the CPU, which is what killed the payroll run.
The Jenkins agent was restarted. The payroll run was restarted. Everyone is monitoring it, and they’re confident it will complete by 13:00.”
There is no evidence here, but it clearly describes what happened, and what is being done about it. If I didn’t feel confident about closing the email after the first level, I should now.
Level 3 and Beyond
In the case of an email, I don’t think anything beyond this point makes sense. Large emails and posts look daunting, and I get the impression people just “file them” to be looked at later. Maybe that’s just me. 🙂
In most cases, I think anything level 3 downward should be a link to something, so those people that are interested can “get their geek on”, while everyone else gets on with their day. Something like this for example.
Incident : INC123456
Problem Record : PRB123456 : How do we prevent Jenkins agents killing our stuff?
Knowledge Base: KB123456 : Diagnosing Payroll Run Failures.
Knowledge Base: KB234567 : What is Jenkins and why do we use it?”
This doesn’t add much to the size of the email, but it does give people a place to go if they need more information.
I’m making the assumption that people in the company know the evidence of the issue diagnosis and corrective actions will be included in the P1 incident, so I don’t need to add it into the email. The problem record shows we’ve got some thinking to do to make sure this doesn’t happen again. The knowledge base notes give us a place to get further information, and give us some confidence that if Jayne dies, we might still get paid next month.
I’ve been producing content for a while, and occasionally I have light-bulb moments where I realise I’ve totally missed the point. Several years after writing an article about the Oracle Scheduler I realised the vast majority of people just want a basic example they can copy/paste. I added a section to the top of the article (here). I doubt many people move beyond that. I rarely do. 🙂
There is little point writing something unless you think someone is going to read it, even if it is yourself. You need to get the correct information to the correct people as quickly as possible. That involves thinking about the way you present your content and write your emails. I’m not saying this is perfect. I’m not an expert at this stuff. This is just how I feel about it, and I think the pyramid approach discussed in the course is a good mental cue to keep you on track.
PS. You are not allowed to use this against me when you see one of my rambling posts or articles.
PPS. In real life it wasn’t a payroll system, but it was a Jenkins agent that killed everything.
PPPS. Everyone knows it’s always the network! 🙂