September 26, 2020 • 25 mins
Have you ever come across documentation for a library or framework that was so good it made development painless? As it turns out, there's a whole field responsible for making that feeling a reality: technical writing. Lucas Costi is a technical writer at GitHub (you might have heard of it) and he's kindly joined us to talk about what his role involves and how he's combined technical and writing skills to produce stellar documentation for Red Hat and GitHub. He and Liv also discuss how poor documentation can be an incredible motivator for putting together something better.
Liking The Router so far, why not subscribe in your favourite podcast app? Check out https://router.uqcs.org/ for details.
Intro/Outro Music: Awesome Call by Kevin MacLeod
Link: https://incompetech.filmmusic.io/song/3399-awesome-call
License: http://creativecommons.org/licenses/by/4.0/
Mark as Played
Transcript
Episode Transcript
Available transcripts are automatically generated. Complete accuracy is not guaranteed.
Speaker 1 (00:00):
Hello, and welcome to the router, the official podcast
of the ACU computing society,where we explore the human side
of tech.
I'm your host, Olivia.
And on this week's episode,we'll be talking to Lucas.
Costy about his experience as atechnical writer.
(00:25):
First things first, tell me alittle bit about yourself and
what you do.
Speaker 2 (00:30):
Cool.
Um, hi, my name is Lukas Costie.
Uh, I work at, uh, as atechnical writer and currently
I'm working at GitHub.
You may have heard of it.
Uh, I previously worked as a,uh, as a technical writer at red
hat.
And then before that I worked init support and system
(00:53):
administration.
So I sorta changed careers frombeing a CIS admin to a technical
writer about seven or eightyears ago.
Speaker 1 (01:01):
Oh yeah.
Um, so what decided you to makethat change to technical
writing?
Speaker 2 (01:07):
Well, um, I'd always been a really good writer even
from school and, uh, to go backa little bit towards my time at
Yuku.
Um, I actually started ajournalism career, um,
journalism degree, um, as myfirst thing out of high school,
but it took me about four weeksinto the semester of journalism
(01:31):
to realize that I wasn't cut outfor journalism and, um, switched
back to an arts degree, whichwas my initial plan out of
school.
Um, and I did a few it coursesin that and discovered I loved
technology as well.
So I completed a bachelor of itand a bachelor of arts.
(01:51):
Um, as you can imagine, thosetwo timetables didn't work very
well.
Um, but, um, I, uh, I liked thetechnology, but I also liked the
writing part.
So anyway, fast forward towardsgraduation, I really needed a
job quickly because I wasgetting married at the time.
So I just took, um, the firstjob I could find, which was a,
(02:15):
um, a support job, which overthe years I transitioned into
being like a systemadministrator and it was
comfortable and it paid okay.
Um, but I wasn't really happy bythe end of it.
Um, so about five years intothat, um, I actually got really
sick and I had to stop working,um, to deal with my health.
(02:40):
And, um, and after I sort of gotback to, uh, uh, like a time
where I could, um, go back towork full time, I sort of had a
discussion with my wife and withmyself of like, well, do I
really want to go back to beinga CIS admin?
And, um, and I really didn'twant it.
(03:01):
And I thought, well, what elsecould I do as a job?
And I briefly flirted with theidea of writing a book, um, but
realized that I can't really, uh, I can't take criticism of my
creative stuff very well.
So I started looking around, um,in other careers and, um, I
(03:23):
still love technology and Ireally liked writing.
So I thought, Hey, is there anytoo, I mean, is there any career
that can mix the two of thosethings?
And it turned out there is athing called technical writing.
And luckily for me, um, red hathere in Brisbane was hiring new
technical writers at the time.
And so, um, yeah, I got a jobthere and, uh, and the rest is
(03:46):
history, I suppose.
Speaker 1 (03:48):
Yeah.
So when, when you, I guess likea lot of people, like you don't
really know that much about thetechnical writing role, um,
because even if people have kindof heard of it, there's, it's a
little bit mystified in what iskind of actually done within it.
Would you be able to talk about,I guess maybe some of the
(04:08):
projects that you've worked onover the years?
Speaker 2 (04:12):
Yeah, sure.
So, um, at red hat, um, Iactually worked mainly, I worked
on a lot of products, but I workmainly on what's what was
called, well, what is it called?
Um, J boss enterpriseapplication platform.
And, um, if you haven't heard ofit, it's essentially a Java
(04:33):
application server.
And so I worked primarily onthat at my time at red hat, but
I worked on a ton of otherthings, um, at GitHub at the
moment I'm working on, um, uh,what and get how we call the
ecosystem side of GitHub, whichincludes the GitHub API.
(04:53):
And, um, more recently, um,documenting GitHub actions,
which is get hubs new, um, CIC Duh, system built into GitHub.
So, um, uh, lots of differentproducts covering lots of
different sort of, uh, platformsand uses.
(05:13):
And I guess that's one of thereally great things about
technical writing at, um,relatively large technology
companies is that you getexposed to a lot of different
technologies and a lot ofdifferent things.
Um, a lot of which is really newand exciting.
And so you get to be on thatsort of cutting edge or bleeding
(05:36):
edge of things and learningabout a lot of new stuff, which
really helps in terms of likeyour, uh, exposure to technology
and the industry as a whole.
Speaker 1 (05:51):
Hmm.
Yeah.
That's, it's very, I feel likeit would be very cool cause you
really wouldn't get exposure toall the latest and greatest
technology before, I supposebefore a lot of other people,
um, being the one who has towrite on it.
Um, what, what was your, what'slike one of your favorite, one
of your favorite things thatyou've worked on?
Speaker 2 (06:13):
Well, that's a tough question because I'm at least
personally as a technicalwriter, you tend to develop a
love, hate relationship with thestuff that you're documenting,
um, because you, you sort of,you have to try and understand
(06:33):
what the product is doingwithout having any actual
documentation for it becauseyou're the one writing the
documentation.
So, um, uh, to answer thequestion about the favorite
thing that I've documented, um,Oh geez.
(06:55):
I, I think originally it wouldbe right at the start of my
technical writing career andthat would be with J boss EAP.
And the reason for that is, um,it's actually one of the reasons
(07:17):
that I gave, well, let I giveinterviews when I go for a new
job is, um, I like to be able tohelp, um, people understand, um,
complex things, uh, that needthat information at the time.
And why I say J boss is that, uh, when I was assistant
(07:41):
administrator, I was actuallyadministering a, uh, Apple, um,
excerpt server back when Appleused to actually make servers.
And, um, and they actually had aversion of J boss built into the
actual Apple operating system.
And, um, and I remember it beingso difficult to understand and
(08:02):
use because it was so poorlydocumented within the Apple's
server documentation.
Cause they didn't really do agood effort that sort of
documenting much of the servicespecific stuff that, um, that it
was quite ironic that eventuallywhen I got a job, um, as a
technical writer, that I wassort of not documenting stuff on
(08:24):
Apple, but like documentingessentially the same open source
products that motivated me tosort of, um, become a technical
writer in the first place.
And that's to sort of helppeople understand complex
systems.
Speaker 1 (08:38):
Yeah.
That's, that's very cool.
I guess, that you got toexperience the struggles of not
having good tactical writing andthen adjusted to basically fix
it so that there was actuallydecent some, some decent
documentation there for uses.
Speaker 2 (08:53):
Yeah.
And I think that's what, at myopinion, um, makes me a decent
technical writer is part ofknowing that, that struggle of
like, you know, trying to learnsomething new and trying to
understand what is pretty muchlike a very complex topic and
being on the other side of thatand helping at least trying to
(09:14):
help, um, you know, fix thatsort of situation for people
that would be where I was like10 or so years ago.
Speaker 1 (09:25):
Yeah.
Um, so I guess now that you aremore on like obviously the
writing side, how did you findgiving up or not, not giving up
so much, but like transitioningover from like the more
technical side to, um, like kindof a little bit over to the
other side, like obviously youstill have a very technical
(09:45):
based role, but it's not ashands on with the technical
stuff as you would havepreviously had.
Speaker 2 (09:53):
Um, I actually really enjoy it because at least for
myself, I don't feel as muchpressure in that.
Like I'm not in charge of like,um, keeping a production system
running and being responsiblefor like everybody's
productivity inside a company orsomething like that.
(10:14):
But, um, but I still get to, um,get really hands on with things
and, um, not, not all technicalwriters are like this, but I
like to get really hands on withsomething that I'm documenting
to make sure that, um,essentially it is what, sorry,
what I'm documenting is actuallyaccurate for what say the
(10:36):
product or the feature actuallydoes.
So, um, as I said before, itsort of gives me really broad
access to a lot of differenttechnologies and, um, and parts
of features that I would neverhave sort of touched before, um,
to get in there and actuallyplay with it and then to figure
(10:57):
out how people would want to useit or might want to use it.
And, uh, and then actually writedocumentation that explains how
it works and how people canactually, uh, use it to
accomplish their own sort ofbusiness needs or user needs.
Speaker 1 (11:14):
Hmm.
Yeah, I think that's prettygood.
Um, pretty good reasoning math.
So I guess I'm kind of on alittle bit of a different
tangent, but how, how would youget started in technical
writing?
I know you said you like kind ofapplied for red hat and then got
(11:35):
the position there, but I feellike it can definitely be a, a
tricky position to get into.
Do you have any tips for gettingthere?
Speaker 2 (11:48):
Yeah.
I mean, it's one of those thingslike with any career, there's
always a bit of luck gettingstarted.
Um, first of all, um, I wouldsay to anybody wanting to be a
technical writer is that like,of course being able to write
and having a good understandingof like English grammar and what
makes good sentences and thingslike that, um, would be the
(12:13):
first thing that you shoulddefinitely work on in terms of
actually getting your foot inthe door at certain places.
Um, it's always good to haveexamples of like what you've
done before in terms oftechnical writing and something
that a lot of people alwayssuggest and I think is great as
well is to get involved in maybesomething like some open source
(12:35):
projects that might not havegood documentation coverage and
just write a few like a guidesor how tos or tutorials or
something like that on theactual open source product or
feature or like scripts orwhatever it is on ghetto and
just contribute to thatcommunity so that you can
(12:58):
actually have something that youcan show, um, as sort of like a
portfolio essentially of stuffthat you've done.
And, um, and so, yeah, I mean,if you use like an S you know,
some something that's opensource on GitHub or wherever
else, um, and you can show thatyou've contributed to that and
(13:20):
that you have an understandingof like what the thing does and
maybe how to explain how to useit to somebody who might not be
familiar.
Um, I think that's a great startto, um, to sort of, you know,
build up some examples of yourwriting that you can actually
show, um, if you're going for anew job.
Speaker 1 (13:39):
Yeah.
Yeah.
Okay.
Um, yeah, I feel like I opensource working, contributing and
working on open source projectsis honestly a good, a good bit
of advice for anyone in any kindof technical field, because I
feel like they do really exposeyou to, um, so not sure, like
what's so much differenttechnology, but, and working
(14:00):
with other people as well,especially, um, because
obviously you're working opensource, you're working with a
whole bunch of all thedevelopers and writers together.
Um, but how do you, how do youfind working within a technical
writing, um, team and obviouslylike you would have to have a
lot of, uh, I guess providingfeedback to others and feedback
(14:24):
provided on yourself.
Cause you mentioned that youfind it difficult to find, to
take creative criticism.
Speaker 2 (14:32):
Uh, yeah.
Um, I love working on a team.
That's probably one of myfavorite things and why I've
generally shied away from jobsthat have like, that are more
solo type of technical writing.
Um, when I mentioned beforeabout like taking creative, it's
more something like creative,like writing a book rather than
(14:56):
creative, like writing a, like atechnical guide.
So, um, uh, I've been lucky that, um, both previously at red hat
and of course now I get hub isthat we all, um, use, uh, get
and, uh, repositories to writeand store our documentation
(15:19):
before it gets processed into amore readable form, like a
website.
So, um, we use a, you know, apull request, um, review sort of
get flow process, um, in all ofour work.
So everything that getscommitted into the repository
has to be reviewed by somebodyelse.
(15:40):
Um, and you have that sort ofdiscussion like you do on any
normal sort of repository ofcode where multiple people are
working, um, on reviews andthings like that.
So, um, uh, as I said, it's oneof my favorite parts of
technical writing because, uh,no matter how experienced you
(16:01):
think you are, even just interms of writing with just
English and stuff like that,you're always learning something
new.
Um, there's always bad habitsthat you have that other people
point out that you don't realizethat you haven't until somebody
points it out.
Um, and like, just like withcode that there's like a ton of
(16:21):
different ways of programming,something to achieve an output
it's sorta the same with writingis that there's so many
different ways that you canwrite something and explain
something.
And a lot of the times you can'teven see the different methods
after you've written one thing,and somebody will come along and
point out a much better, muchcleaner, much more succinct way
(16:45):
of explaining something that youcan't believe that you didn't
sort of see that in the firstplace.
So I'm sort of a big thing intechnical writing at the moment
is treating docs as codeessentially both in the way it's
stored and that it's wayscollaborated on.
Um, and I'm a big fan of thatbecause I think, um, reviews and
(17:08):
, um, a collaborative process ingenerating docs is just as
useful as the actual code of theproduct itself as well.
Speaker 1 (17:18):
Yeah, it's really, really interesting and cool.
I think to hear that you guysuse get for technical writing as
well.
Um, because it is a, like a, agood system for systematically,
um, developing, um, I suppose inthis case, like writing and you
can see other people's edits andyeah, I think that's really cool
and interesting.
Um, I guess my, my last kind ofquestion that I have written
(17:41):
down here is in terms of likethe progression of technical
writer, like, what is the kindof career progression from, um,
just like when you first startedout to, um, later on, uh,
Speaker 2 (17:59):
There is tons of different things that you can do
in technical writing.
And, um, I've known people,who've been developers and
engineers and come in astechnical writers and I've known
technical writers that have likebeen writers and moved on to
engineering type of roles, butjust within technical writing
itself, um, you can be, what'susually called like an
(18:23):
individual contributor, which is, um, you're a writer, you
produce docs.
Um, and that's sort of likewhere I like to be.
And usually just like in anengineering role, there's like a
career progression from beinglike a, uh, a sort of like start
a technical writer up to likesenior and principal or staff
(18:45):
technical writing roles.
Um, uh, and then of course justlike engineering teams, um,
usually, uh, teams or technicalwriters will have their own, um,
like management as well.
So there's technical writermanagers, um, pretty much, um,
producing docs for any sizableproduct requires a lot of
(19:08):
project management as well.
So there is just as there's like, um, engineering product
managers for a particular likefeature or product.
Um, there's also product I'msorry, documentation, product
managers.
Speaker 1 (19:26):
Okay.
Speaker 2 (19:26):
And the other side of it as well is that, um, any good
set of docs also needs a goodset of engineering to actually,
um, process those docs andpresent them.
So, um, I've been lucky at sortof the two large companies that
I've worked at as a technicalwriter that we've had our own
dedicated docs engineering team,um, because we have such a large
(19:51):
amount of content.
Uh, it does take a lot of customwork to sort of stitch that
together and present it in a, ina, in a nice way across a lot of
different formats.
Um, and that involves a lot oflike, uh, reuse and, um, and
sort of massaging of pretty muchour source documentation to get
(20:16):
it to what you see at the end.
Um, so if you're familiar, Ithink, um, uh, the QCs did a
presentation of, uh, ASCII doc,I think last year or something.
And, um, uh, that's a reallypowerful system as well.
Um, like it's a lot more, um,complex than just sort of
(20:36):
writing sentences down in a, ina text file.
Um, you can have things likereusables and, um, conditions
and things like that in your doc.
So that depending on who isgiving it for what product, for
example, it can show somethingdifferent.
So, um, so like dogs engineeringis a way to get into it.
Um, and yeah, generally there'sso many different things just
(21:00):
within documentation that youcan do as a career.
Um, one thing I haven'tmentioned that I, of course,
should men should mention aswell, is that, um, in most big
teams as what's called adocumentation content strategist
, and they sort of can plan outand set sort of the direction on
(21:22):
a more larger scale for a set ofdocumentation and provide rules
and stuff, or how it should bedocumented and what kind of, um,
like system or like templatesthat we should use to document
things.
So, um, that's one thing I'velearned from my career and
(21:43):
documentation is that like, whatmight seem simple from the
outside does take a lot of workand a lot of different people
and a lot of different roles toactually like produce what end
users actually see and read.
Speaker 1 (21:58):
Hmm.
Thank you for that.
That's very interesting to hear.
I like the such large diversity,I suppose, overall, so there
really is.
Um, but yeah, that's, that's allI have to ask you for today.
Is there anything else you feellike mentioning or adding for
anyone potentially looking atpursuing a career in technical
writing?
Speaker 2 (22:20):
Uh, yeah.
Um, I think one of my otherbiggest suggestions is just to
be curious about things, um,because, uh, at least for myself
doing documentation, um, prettymuch that curiosity is I think
(22:42):
what helps me write gooddocumentation in that you always
want to know how people usethings and how something works,
and that's sort of a good basisfor how you can actually
describe, um, and help otherpeople use what you're curious
about.
(23:03):
Um, I think that if you're likeme, that you enjoy explaining
things and that you can actuallywrite a decent English and
you're pretty good with techthen, like I think technical
writing can be really valuablecareer, um, that you can still
be in technology and still usereally exciting stuff.
(23:27):
Um, but still also like helppeople and use your writing
skills to really produce somereally complex things that are
really cool.
Um, so yeah, hopefully thatanswered the question.
Speaker 1 (23:41):
Yeah.
Yeah, for sure.
That was a really, that wasactually a really response.
Um, well, yeah.
Thank you so much for joining metoday.
It was really fantastic to haveyou on you're a great, a great
speaker and have a really great,um, like it's like story to
tell.
I feel like we'll be a lot ofpeople like will be very
(24:02):
interested to hear and probablya lot of people following it as
well.
I feel like, um, your, your likestarting out in, in a role that
you weren't really so happywith, and then moving over to
technical writing, I'm sure willreally, um, strike to strike a
note with a lot of people, um,who might be wanting to pursue a
(24:22):
similar thing, you know?
Speaker 2 (24:23):
Yeah.
And I think that's one of justgenerally with technology in
general and it that's one of thegreat things about the industry
is that, um, no matter where youstart off in what you're doing,
there is so much variety, um,in, in the whole industry that
if you really want to changecareers to do something else,
(24:45):
and you've got that motivationto that, it's pretty skills are
pretty transferable across likea lot of different things in
technology.
So like, just because you startoff doing one thing, doesn't
mean you're locked into thatthing forever.
And, um, and as long as likeyou're willing to learn and
you're willing to like, um, sortof start new things and be a bit
(25:09):
uncomfortable then, um, there'sno reason why, like, you can't
just change things up in themiddle of your career and do
something new and somethingbetter that makes you more
happy, I suppose.
Speaker 1 (25:23):
Yeah, yeah, yeah, for sure.
And that's what we have to stay.
Please join us again in twoweeks from now for our next
episode until then come join ourcommunity at Slack.
What UGCs dog.
Hello, and welcome to the router, the official podcast
of the ACU computing society,where we explore the human side
of tech.
I'm your host, Olivia.
And on this week's episode,we'll be talking to Lucas.
Costy about his experience as atechnical writer.
(00:25):
First things first, tell me alittle bit about yourself and
what you do.
Speaker 2 (00:30):
Cool.
Um, hi, my name is Lukas Costie.
Uh, I work at, uh, as atechnical writer and currently
I'm working at GitHub.
You may have heard of it.
Uh, I previously worked as a,uh, as a technical writer at red
hat.
And then before that I worked init support and system
(00:53):
administration.
So I sorta changed careers frombeing a CIS admin to a technical
writer about seven or eightyears ago.
Speaker 1 (01:01):
Oh yeah.
Um, so what decided you to makethat change to technical
writing?
Speaker 2 (01:07):
Well, um, I'd always been a really good writer even
from school and, uh, to go backa little bit towards my time at
Yuku.
Um, I actually started ajournalism career, um,
journalism degree, um, as myfirst thing out of high school,
but it took me about four weeksinto the semester of journalism
(01:31):
to realize that I wasn't cut outfor journalism and, um, switched
back to an arts degree, whichwas my initial plan out of
school.
Um, and I did a few it coursesin that and discovered I loved
technology as well.
So I completed a bachelor of itand a bachelor of arts.
(01:51):
Um, as you can imagine, thosetwo timetables didn't work very
well.
Um, but, um, I, uh, I liked thetechnology, but I also liked the
writing part.
So anyway, fast forward towardsgraduation, I really needed a
job quickly because I wasgetting married at the time.
So I just took, um, the firstjob I could find, which was a,
(02:15):
um, a support job, which overthe years I transitioned into
being like a systemadministrator and it was
comfortable and it paid okay.
Um, but I wasn't really happy bythe end of it.
Um, so about five years intothat, um, I actually got really
sick and I had to stop working,um, to deal with my health.
(02:40):
And, um, and after I sort of gotback to, uh, uh, like a time
where I could, um, go back towork full time, I sort of had a
discussion with my wife and withmyself of like, well, do I
really want to go back to beinga CIS admin?
And, um, and I really didn'twant it.
(03:01):
And I thought, well, what elsecould I do as a job?
And I briefly flirted with theidea of writing a book, um, but
realized that I can't really, uh, I can't take criticism of my
creative stuff very well.
So I started looking around, um,in other careers and, um, I
(03:23):
still love technology and Ireally liked writing.
So I thought, Hey, is there anytoo, I mean, is there any career
that can mix the two of thosethings?
And it turned out there is athing called technical writing.
And luckily for me, um, red hathere in Brisbane was hiring new
technical writers at the time.
And so, um, yeah, I got a jobthere and, uh, and the rest is
(03:46):
history, I suppose.
Speaker 1 (03:48):
Yeah.
So when, when you, I guess likea lot of people, like you don't
really know that much about thetechnical writing role, um,
because even if people have kindof heard of it, there's, it's a
little bit mystified in what iskind of actually done within it.
Would you be able to talk about,I guess maybe some of the
(04:08):
projects that you've worked onover the years?
Speaker 2 (04:12):
Yeah, sure.
So, um, at red hat, um, Iactually worked mainly, I worked
on a lot of products, but I workmainly on what's what was
called, well, what is it called?
Um, J boss enterpriseapplication platform.
And, um, if you haven't heard ofit, it's essentially a Java
(04:33):
application server.
And so I worked primarily onthat at my time at red hat, but
I worked on a ton of otherthings, um, at GitHub at the
moment I'm working on, um, uh,what and get how we call the
ecosystem side of GitHub, whichincludes the GitHub API.
(04:53):
And, um, more recently, um,documenting GitHub actions,
which is get hubs new, um, CIC Duh, system built into GitHub.
So, um, uh, lots of differentproducts covering lots of
different sort of, uh, platformsand uses.
(05:13):
And I guess that's one of thereally great things about
technical writing at, um,relatively large technology
companies is that you getexposed to a lot of different
technologies and a lot ofdifferent things.
Um, a lot of which is really newand exciting.
And so you get to be on thatsort of cutting edge or bleeding
(05:36):
edge of things and learningabout a lot of new stuff, which
really helps in terms of likeyour, uh, exposure to technology
and the industry as a whole.
Speaker 1 (05:51):
Hmm.
Yeah.
That's, it's very, I feel likeit would be very cool cause you
really wouldn't get exposure toall the latest and greatest
technology before, I supposebefore a lot of other people,
um, being the one who has towrite on it.
Um, what, what was your, what'slike one of your favorite, one
of your favorite things thatyou've worked on?
Speaker 2 (06:13):
Well, that's a tough question because I'm at least
personally as a technicalwriter, you tend to develop a
love, hate relationship with thestuff that you're documenting,
um, because you, you sort of,you have to try and understand
(06:33):
what the product is doingwithout having any actual
documentation for it becauseyou're the one writing the
documentation.
So, um, uh, to answer thequestion about the favorite
thing that I've documented, um,Oh geez.
(06:55):
I, I think originally it wouldbe right at the start of my
technical writing career andthat would be with J boss EAP.
And the reason for that is, um,it's actually one of the reasons
(07:17):
that I gave, well, let I giveinterviews when I go for a new
job is, um, I like to be able tohelp, um, people understand, um,
complex things, uh, that needthat information at the time.
And why I say J boss is that, uh, when I was assistant
(07:41):
administrator, I was actuallyadministering a, uh, Apple, um,
excerpt server back when Appleused to actually make servers.
And, um, and they actually had aversion of J boss built into the
actual Apple operating system.
And, um, and I remember it beingso difficult to understand and
(08:02):
use because it was so poorlydocumented within the Apple's
server documentation.
Cause they didn't really do agood effort that sort of
documenting much of the servicespecific stuff that, um, that it
was quite ironic that eventuallywhen I got a job, um, as a
technical writer, that I wassort of not documenting stuff on
(08:24):
Apple, but like documentingessentially the same open source
products that motivated me tosort of, um, become a technical
writer in the first place.
And that's to sort of helppeople understand complex
systems.
Speaker 1 (08:38):
Yeah.
That's, that's very cool.
I guess, that you got toexperience the struggles of not
having good tactical writing andthen adjusted to basically fix
it so that there was actuallydecent some, some decent
documentation there for uses.
Speaker 2 (08:53):
Yeah.
And I think that's what, at myopinion, um, makes me a decent
technical writer is part ofknowing that, that struggle of
like, you know, trying to learnsomething new and trying to
understand what is pretty muchlike a very complex topic and
being on the other side of thatand helping at least trying to
(09:14):
help, um, you know, fix thatsort of situation for people
that would be where I was like10 or so years ago.
Speaker 1 (09:25):
Yeah.
Um, so I guess now that you aremore on like obviously the
writing side, how did you findgiving up or not, not giving up
so much, but like transitioningover from like the more
technical side to, um, like kindof a little bit over to the
other side, like obviously youstill have a very technical
(09:45):
based role, but it's not ashands on with the technical
stuff as you would havepreviously had.
Speaker 2 (09:53):
Um, I actually really enjoy it because at least for
myself, I don't feel as muchpressure in that.
Like I'm not in charge of like,um, keeping a production system
running and being responsiblefor like everybody's
productivity inside a company orsomething like that.
(10:14):
But, um, but I still get to, um,get really hands on with things
and, um, not, not all technicalwriters are like this, but I
like to get really hands on withsomething that I'm documenting
to make sure that, um,essentially it is what, sorry,
what I'm documenting is actuallyaccurate for what say the
(10:36):
product or the feature actuallydoes.
So, um, as I said before, itsort of gives me really broad
access to a lot of differenttechnologies and, um, and parts
of features that I would neverhave sort of touched before, um,
to get in there and actuallyplay with it and then to figure
(10:57):
out how people would want to useit or might want to use it.
And, uh, and then actually writedocumentation that explains how
it works and how people canactually, uh, use it to
accomplish their own sort ofbusiness needs or user needs.
Speaker 1 (11:14):
Hmm.
Yeah, I think that's prettygood.
Um, pretty good reasoning math.
So I guess I'm kind of on alittle bit of a different
tangent, but how, how would youget started in technical
writing?
I know you said you like kind ofapplied for red hat and then got
(11:35):
the position there, but I feellike it can definitely be a, a
tricky position to get into.
Do you have any tips for gettingthere?
Speaker 2 (11:48):
Yeah.
I mean, it's one of those thingslike with any career, there's
always a bit of luck gettingstarted.
Um, first of all, um, I wouldsay to anybody wanting to be a
technical writer is that like,of course being able to write
and having a good understandingof like English grammar and what
makes good sentences and thingslike that, um, would be the
(12:13):
first thing that you shoulddefinitely work on in terms of
actually getting your foot inthe door at certain places.
Um, it's always good to haveexamples of like what you've
done before in terms oftechnical writing and something
that a lot of people alwayssuggest and I think is great as
well is to get involved in maybesomething like some open source
(12:35):
projects that might not havegood documentation coverage and
just write a few like a guidesor how tos or tutorials or
something like that on theactual open source product or
feature or like scripts orwhatever it is on ghetto and
just contribute to thatcommunity so that you can
(12:58):
actually have something that youcan show, um, as sort of like a
portfolio essentially of stuffthat you've done.
And, um, and so, yeah, I mean,if you use like an S you know,
some something that's opensource on GitHub or wherever
else, um, and you can show thatyou've contributed to that and
(13:20):
that you have an understandingof like what the thing does and
maybe how to explain how to useit to somebody who might not be
familiar.
Um, I think that's a great startto, um, to sort of, you know,
build up some examples of yourwriting that you can actually
show, um, if you're going for anew job.
Speaker 1 (13:39):
Yeah.
Yeah.
Okay.
Um, yeah, I feel like I opensource working, contributing and
working on open source projectsis honestly a good, a good bit
of advice for anyone in any kindof technical field, because I
feel like they do really exposeyou to, um, so not sure, like
what's so much differenttechnology, but, and working
(14:00):
with other people as well,especially, um, because
obviously you're working opensource, you're working with a
whole bunch of all thedevelopers and writers together.
Um, but how do you, how do youfind working within a technical
writing, um, team and obviouslylike you would have to have a
lot of, uh, I guess providingfeedback to others and feedback
(14:24):
provided on yourself.
Cause you mentioned that youfind it difficult to find, to
take creative criticism.
Speaker 2 (14:32):
Uh, yeah.
Um, I love working on a team.
That's probably one of myfavorite things and why I've
generally shied away from jobsthat have like, that are more
solo type of technical writing.
Um, when I mentioned beforeabout like taking creative, it's
more something like creative,like writing a book rather than
(14:56):
creative, like writing a, like atechnical guide.
So, um, uh, I've been lucky that, um, both previously at red hat
and of course now I get hub isthat we all, um, use, uh, get
and, uh, repositories to writeand store our documentation
(15:19):
before it gets processed into amore readable form, like a
website.
So, um, we use a, you know, apull request, um, review sort of
get flow process, um, in all ofour work.
So everything that getscommitted into the repository
has to be reviewed by somebodyelse.
(15:40):
Um, and you have that sort ofdiscussion like you do on any
normal sort of repository ofcode where multiple people are
working, um, on reviews andthings like that.
So, um, uh, as I said, it's oneof my favorite parts of
technical writing because, uh,no matter how experienced you
(16:01):
think you are, even just interms of writing with just
English and stuff like that,you're always learning something
new.
Um, there's always bad habitsthat you have that other people
point out that you don't realizethat you haven't until somebody
points it out.
Um, and like, just like withcode that there's like a ton of
(16:21):
different ways of programming,something to achieve an output
it's sorta the same with writingis that there's so many
different ways that you canwrite something and explain
something.
And a lot of the times you can'teven see the different methods
after you've written one thing,and somebody will come along and
point out a much better, muchcleaner, much more succinct way
(16:45):
of explaining something that youcan't believe that you didn't
sort of see that in the firstplace.
So I'm sort of a big thing intechnical writing at the moment
is treating docs as codeessentially both in the way it's
stored and that it's wayscollaborated on.
Um, and I'm a big fan of thatbecause I think, um, reviews and
(17:08):
, um, a collaborative process ingenerating docs is just as
useful as the actual code of theproduct itself as well.
Speaker 1 (17:18):
Yeah, it's really, really interesting and cool.
I think to hear that you guysuse get for technical writing as
well.
Um, because it is a, like a, agood system for systematically,
um, developing, um, I suppose inthis case, like writing and you
can see other people's edits andyeah, I think that's really cool
and interesting.
Um, I guess my, my last kind ofquestion that I have written
(17:41):
down here is in terms of likethe progression of technical
writer, like, what is the kindof career progression from, um,
just like when you first startedout to, um, later on, uh,
Speaker 2 (17:59):
There is tons of different things that you can do
in technical writing.
And, um, I've known people,who've been developers and
engineers and come in astechnical writers and I've known
technical writers that have likebeen writers and moved on to
engineering type of roles, butjust within technical writing
itself, um, you can be, what'susually called like an
(18:23):
individual contributor, which is, um, you're a writer, you
produce docs.
Um, and that's sort of likewhere I like to be.
And usually just like in anengineering role, there's like a
career progression from beinglike a, uh, a sort of like start
a technical writer up to likesenior and principal or staff
(18:45):
technical writing roles.
Um, uh, and then of course justlike engineering teams, um,
usually, uh, teams or technicalwriters will have their own, um,
like management as well.
So there's technical writermanagers, um, pretty much, um,
producing docs for any sizableproduct requires a lot of
(19:08):
project management as well.
So there is just as there's like, um, engineering product
managers for a particular likefeature or product.
Um, there's also product I'msorry, documentation, product
managers.
Speaker 1 (19:26):
Okay.
Speaker 2 (19:26):
And the other side of it as well is that, um, any good
set of docs also needs a goodset of engineering to actually,
um, process those docs andpresent them.
So, um, I've been lucky at sortof the two large companies that
I've worked at as a technicalwriter that we've had our own
dedicated docs engineering team,um, because we have such a large
(19:51):
amount of content.
Uh, it does take a lot of customwork to sort of stitch that
together and present it in a, ina, in a nice way across a lot of
different formats.
Um, and that involves a lot oflike, uh, reuse and, um, and
sort of massaging of pretty muchour source documentation to get
(20:16):
it to what you see at the end.
Um, so if you're familiar, Ithink, um, uh, the QCs did a
presentation of, uh, ASCII doc,I think last year or something.
And, um, uh, that's a reallypowerful system as well.
Um, like it's a lot more, um,complex than just sort of
(20:36):
writing sentences down in a, ina text file.
Um, you can have things likereusables and, um, conditions
and things like that in your doc.
So that depending on who isgiving it for what product, for
example, it can show somethingdifferent.
So, um, so like dogs engineeringis a way to get into it.
Um, and yeah, generally there'sso many different things just
(21:00):
within documentation that youcan do as a career.
Um, one thing I haven'tmentioned that I, of course,
should men should mention aswell, is that, um, in most big
teams as what's called adocumentation content strategist
, and they sort of can plan outand set sort of the direction on
(21:22):
a more larger scale for a set ofdocumentation and provide rules
and stuff, or how it should bedocumented and what kind of, um,
like system or like templatesthat we should use to document
things.
So, um, that's one thing I'velearned from my career and
(21:43):
documentation is that like, whatmight seem simple from the
outside does take a lot of workand a lot of different people
and a lot of different roles toactually like produce what end
users actually see and read.
Speaker 1 (21:58):
Hmm.
Thank you for that.
That's very interesting to hear.
I like the such large diversity,I suppose, overall, so there
really is.
Um, but yeah, that's, that's allI have to ask you for today.
Is there anything else you feellike mentioning or adding for
anyone potentially looking atpursuing a career in technical
writing?
Speaker 2 (22:20):
Uh, yeah.
Um, I think one of my otherbiggest suggestions is just to
be curious about things, um,because, uh, at least for myself
doing documentation, um, prettymuch that curiosity is I think
(22:42):
what helps me write gooddocumentation in that you always
want to know how people usethings and how something works,
and that's sort of a good basisfor how you can actually
describe, um, and help otherpeople use what you're curious
about.
(23:03):
Um, I think that if you're likeme, that you enjoy explaining
things and that you can actuallywrite a decent English and
you're pretty good with techthen, like I think technical
writing can be really valuablecareer, um, that you can still
be in technology and still usereally exciting stuff.
(23:27):
Um, but still also like helppeople and use your writing
skills to really produce somereally complex things that are
really cool.
Um, so yeah, hopefully thatanswered the question.
Speaker 1 (23:41):
Yeah.
Yeah, for sure.
That was a really, that wasactually a really response.
Um, well, yeah.
Thank you so much for joining metoday.
It was really fantastic to haveyou on you're a great, a great
speaker and have a really great,um, like it's like story to
tell.
I feel like we'll be a lot ofpeople like will be very
(24:02):
interested to hear and probablya lot of people following it as
well.
I feel like, um, your, your likestarting out in, in a role that
you weren't really so happywith, and then moving over to
technical writing, I'm sure willreally, um, strike to strike a
note with a lot of people, um,who might be wanting to pursue a
(24:22):
similar thing, you know?
Speaker 2 (24:23):
Yeah.
And I think that's one of justgenerally with technology in
general and it that's one of thegreat things about the industry
is that, um, no matter where youstart off in what you're doing,
there is so much variety, um,in, in the whole industry that
if you really want to changecareers to do something else,
(24:45):
and you've got that motivationto that, it's pretty skills are
pretty transferable across likea lot of different things in
technology.
So like, just because you startoff doing one thing, doesn't
mean you're locked into thatthing forever.
And, um, and as long as likeyou're willing to learn and
you're willing to like, um, sortof start new things and be a bit
(25:09):
uncomfortable then, um, there'sno reason why, like, you can't
just change things up in themiddle of your career and do
something new and somethingbetter that makes you more
happy, I suppose.
Speaker 1 (25:23):
Yeah, yeah, yeah, for sure.
And that's what we have to stay.
Please join us again in twoweeks from now for our next
episode until then come join ourcommunity at Slack.
What UGCs dog.
Popular Podcasts
On Purpose with Jay Shetty
I’m Jay Shetty host of On Purpose the worlds #1 Mental Health podcast and I’m so grateful you found us. I started this podcast 5 years ago to invite you into conversations and workshops that are designed to help make you happier, healthier and more healed. I believe that when you (yes you) feel seen, heard and understood you’re able to deal with relationship struggles, work challenges and life’s ups and downs with more ease and grace. I interview experts, celebrities, thought leaders and athletes so that we can grow our mindset, build better habits and uncover a side of them we’ve never seen before. New episodes every Monday and Friday. Your support means the world to me and I don’t take it for granted — click the follow button and leave a review to help us spread the love with On Purpose. I can’t wait for you to listen to your first or 500th episode!
The Joe Rogan Experience
The official podcast of comedian Joe Rogan.
Stuff You Should Know
If you've ever wanted to know about champagne, satanism, the Stonewall Uprising, chaos theory, LSD, El Nino, true crime and Rosa Parks, then look no further. Josh and Chuck have you covered.