Are you looking to learn how to write a technical document, which is one of those critical tech
career skills? If so, this video is for you.
Hi, my name is Michael Gibbs and I'm the founder and CEO of GoCloud Architects, and we're an
organization dedicated towards building high performance cloud computing careers. Today,
we're going to talk about how to write a technical document, because that is an absolutely critical
tech career skill. Now, I'm going to tell you how critical it can be and what writing
can do for you. And then we're going to teach you how to write a technical document. Early
in my career, approximately 20 years ago, I was hired by a company called Riverstone
Networks. And my manager said, "We have a gap in our team, we need someone to talk about
IP multicast technologies." And my manager said, "That's going to be you." And I said,
"Great. And I'm going to learn about it as fast as I can."
And what my manager did, he says, "I need you to write this document to help document
it because it's complicated technology and not a lot of people understand it." And I
said, "Sure, got it. I'm on it." So I literally locked myself in a room for basically a month
but I left only basically to eat lunch and go to sleep. And for most part, I was locked
in the room for a month and I did nothing other than research. Now, mind you, I was
already a Cisco Certified Internet Expert, so I knew a lot about IP multicast, but I
did nothing other than research for a month. And at the end of the month, I really had
a firm grasp of IP multicast technologies and I was all excited about it.
So I called my manager and I told them I was starting the document. And when I wrote this
document, I put as much depth as I could in the document. I drew graphics for the document.
I did everything I could to make it better. And then after I put it all down, then I summarized
my document to make it as simple to read as possible. I then took about the 150 pages
of content, squished it down to about 35 pages of content with lots of diagrams, charts,
I produced this document and something amazing happened. I was being requested to speak all
over the world. I was 25 years old and all of a sudden had a massive tech career and
a huge following. And every time I went to present, people were reaching out to me, and
all of this came from learning how to write a technical document because it's such a critical
tech career skill.
So let's talk about how you write a technical document and how the way we were taught in
school, is the exact opposite way to write a technical document. So let's talk about
documentation, and when you're working on how to learn how to document, that is one
of those critical skills for your tech career development program. And if you're a cloud
architect, it's a critical skill for your cloud architect career development program.
So in school, they teach us that you write a long document with complicated words, complicated
vocabulary, because you want to look and sound educated. Now, for example, in my MBA program,
they would say, write a 20 page document on this topic. What they should've said is, write
a two page document on this topic, but have 20 pages worth of information in the document.
But that's not what we did. I went to graduate school twice for two different careers, and
you know what, both times I wrote long academic documents because that's what I was taught
to do. I was even taught to dot things in the American Psychiatric Association format,
APA format. Even for business school and you know what, in a business school, we're not
psychologists and psychiatrists. So we don't need to write that way.
But you know, it was what I was taught to do in school, it's what students all over
the world are taught in business programs and it's the exact opposite about how do I
write than how to write a technical documents. So let's talk about what you should do instead.
First and foremost, you need to identify your audience. Who is they, your audience? Are
they executives? Are they management professionals or are they tech professionals? All of them
have a different perspective and different things they desire to know. An executive is
focused with growing the company and dealing with the challenges of the company and managing
the company and leading the company. That's what they're concerned about. So for example,
if you're writing a technical document and you have a technology solution that can make
the business 20% more efficient, that executive is going to care. And if you write a technical
document about how the technology solution you're going to propose, or this cloud architecture
you're going to propose, can basically make the organization's costs go down or obtain
new sources of revenue, or even have a new competitive advantage, they are going to be
excited and they're going to want to read that.
Now management in general, is going to be concerned with how things work and how to
deploy them from a higher level perspective than the tech professional, but they're going
to want a lot more depth than the executive, because they're going to have to manage these
things. So therefore, they're going to be concerned with a cross between the business
and a cross between the tech, because they're sort of that middle layer.
Now, your tech professionals, they're going to want to know how everything works, how
to deploy them, how to do them. They're going to need a lot of depth. When I worked at Cisco,
I was asked to design a healthcare architecture and I wrote the same document for three different
audiences. I wrote the executive one to really talk about what the architecture could do,
how it worked and why the organization's need it, in three pages. And you know, what it
was widely received. I wrote something for the managers that had approximately 20 pages
in length, and it talked about the technology in a lot more depth and the architectural
components in a lot more depth, because it gave the managers enough information to better
manage their employees, their tech professionals. And what did I write for the tech professionals,
almost a 300 page architecture document, which literally listed everything, how it worked,
why you would use it, the rationale behind things and graphic after graphic, after graphic.
Why? Because they needed that level of depth and nothing else would have been acceptable.
So first and foremost, when you're doing tech writing or business writing, identify your
audience.
Now the next part of what we're going to talk about is writing for readability. First and
foremost, your document should be really easy to see the organization. Your organization
be something like this, an executive summery, which is going to tell the readers why they
should read your paper. You're going to have an introduction which is going to introduce
the concept and tell them what you're going to tell them. From there, you're going to
provide your supporting evidence. And from there, you're going to summarize the things
you've told them in the document. That's the way to write a document to make things flow
easy. So, that's how you organize it.
Now, how do you write it? First and foremost, unlike businesses school or graduate school,
where they teach you to use jargon and complicated vocabulary, not when you write. Write to be
simple and easy to understand. Even executives prefer to read, to less than an eighth grade
level and almost all newspapers, including the academic types are all written below an
eighth grade level, so when you're doing your writing, do it for a reason, people prefer
to read simpler levels. People don't want to work hard for the information, we want
to receive it. So, simple words.
Now, when you're doing tech writing, you may have complicated technologies and complicated
words that you need introduced to the concept. If you do, first do so sparingly and secondly
define them instantly, do not assume your audience knows what any of these things are.
So define them simply. Simple sentence structure whenever possible, write in sentences that
have 11 words or less. A colleague of mine who was an executive coach read my writing
when I got fresh out of business school and she asked me, she said, "Michael, would you
mind if I sent you some information and some coaching on some documentation?" And I said,
"You're willing to coach me?" And then she showed me what to do and when she showed me
how to shorten my sentences, my writing improved and my audience improved so much. So try to
use simple sentences of 11 words or less.
Now when you're writing sentences, if possible, use the active voice versus the passive voice,
because it's going to be easier to read and it's going to make more sense. And use visuals.
Remember there are three kinds of learners out there. There are visual learners, auditory
learners, and kinesthetic learners. Visual learners learn by looking at things. So have
your charts, your tables, your graphics, it's going to help your visual learners. And that's
65% of your population. Auditory learners think in terms of sound. And when they're
going to read it, they're going to hear their voice in their head and they're going to be
fine. They're going to get it from that. So now if you get the visual people, which is
approximately 65% of the population and the auditory people, which are about 30% of the
population, you've got most of them.
Now, the kinesthetic people learn by doing or thinking in terms of feeling, so if you
can include that in your document, great. Ideally you should, but if not, at least you've
captured roughly 95% of the population by writing and using a good, active voice that's
clear and simple to understand, and by using documents, charts and visuals. So I really
want you to remember that, writing skills are critical for technology professionals.
And whether you're a cloud architect, a cloud engineer, a business leader, a sales rep in
technology, learning how to write a technical document can be one of the best things that
you do for your career.
And you know what, in any component of your technical career, your communication skills
matter. So focus on your communication skills for cloud computing and build an amazing cloud
computing career, or just focus on your communication skills in general and build any great type
career. So whether your goal is to be a cloud architect or a cloud computing business leader,
focus on your writing skills for technology professionals and watch your career blossom.
Let me tell you some services and offerings we have for the cloud computing community.
Every Monday and every Thursday, we have a completely free, "How to get your first cloud
architect job" webinar. And on this webinar, we talk to you, we understand you're new technology
professionals, you often have less background and we teach you everything you need to learn
to get your first cloud architect job. Or it could be during a career transition, that's
fine, but we understand what it takes. We teach you what you need to do on an interview.
We teach you what hiring managers desire. We teach you how to build your resume. We
teach you the things to study. Literally everything you need to learn, how to get your first cloud
architect job. We do that on Monday. We do it on Thursday. It is completely free. The
link is in the description below.
Now on most Tuesdays we have a "Cloud architect experience" webinar. Again, this is free and
people come to these webinars and we talk about, how to get the kind of cloud architect
experience that employers will see on your resume, so you can get your first cloud architect
job, because people find themselves in this quandary. You can't get hired without experience,
but how do you get experience unless you're hired? And we're going to teach you how to
do that.
We also on these webinars, frequently have cloud architecture challenges. And what we
do is, we come up with a cloud architecture. We then have you interview us and design a
cloud computing environment from scratch based upon our business legal technical regulatory
requirements. So this is actually live when we do it, free cloud architecture training.
So please join us on one of our Tuesday "Cloud architect experience" webinars. We'll either
tell you how to get experience or may surprise you and have some real fun with cloud computing
architecture training.
Most Wednesdays, we have a YouTube live where we answer any cloud architect career questions.
So please subscribe to the channel. You'll be notified of it. Or if you're in one of
our email lists, we'll usually post it on email or we'll post it to our social media
channels. All of our social media channels are in the description below, please join.
Wanted to let you know about some collaboration things that we're going to be doing for the
cloud architect community. We understand how many people out there need help with their
cloud computing careers. And what we're doing is, we're launching a custom slack channel,
which my team has been working on for approximately a month. We've got all types of collaboration
opportunities. You'll be able to place calls from here. You'll be able to launch live Zoom
calls immediately from our platform. You'll be able to communicate and collaborate on
cloud architecture projects. We are going to be inviting the recruiting community as
well as the public community. And that way we can create an environment where people
can ask us cloud architect career skills, or cloud computing career skills, get cloud
computing career guidance on our channel, and when we're ready, we can ask the right
questions.
Your profile can be exposed to recruiter, and it's going to be exclusively focused on
building cloud computing careers. It's our channel, and it's going to be completely free.
We want to change the way people focus on their cloud computing careers. We don't want
people to just focused on certification. We want people focused on everything necessary
to build the perfect technology career or cloud computing career, whether that's as
a cloud architect, a cloud engineer, someone in [SYSHUB 00:11:58], someone in DevOps. We
want to help you build your cloud computing career.
Last thing I wanted to let you know, we have a couple initiatives to help people get AWS
certified. We are in the coaching business, not certification business, but we understand
certification is essential for people. And because we wanted to find something that we
liked, that we could provide at low cost or free, we have created a free AWS Certified
Solution Architect Associate e-book, and an AWS Certified Solution Architect Associate
e-course. The links to both are free and they are in the description below.
On the week of June 15th through June 20th, on YouTube live, we will be holding a completely
free AWS Certified Solution Architect Professional live bootcamp. The way we're going to run
it, we will have 20 minutes of presentation, 10 minutes of questions for the entire time.
So this will be a free and live cloud architect bootcamp. It's going to be on the week of
June 15th to June 20th. I'll leave the link in description below to sign up for this bootcamp.
We'd love to see you there.
I want to thank you for the opportunity to be communicating with you on our YouTube channel.
It's a big honor to be part of this cloud architect community, and we want to do everything
we can as an organization to help you. If you've got any suggestions, any comments,
any desires, send us a message, we love integrating people's suggestions. Thank you so much for
watching this video. And we look forward to speaking to you soon.