The documentation is part of the software.
So you have to consider the whole user experience that
they're having with your software especially includes the
experience they have when they need help.
If a user is even reading documentation that a technical
writer has produced. They're probably already
annoyed. Hey everyone.
My name is Henry Surya. We Robin.
And you're listening to the tekhelet journal.
The show will be bringing you the greatest technical leaders
practitioners and thought leaders in the industry to
discuss about their Journey ideas and practices that we all
can learn and apply to build a highly performing technical team
and to make an impact in your personal work.
So let's dive into our Journal. Hey everyone, welcome to another
new episode of the tekhelet Juneau podcast.
Very excited to be back here again to share with all of you,
my conversation with another great technical leader in the
industry. Thank you for tuning in and
spending your time with me today, listening to this
episode. If you are new to the podcast,
know that technology, you know, is available on major podcast
apps, such as Spotify, Apple podcast, Google podcast, YouTube
and many more And make sure to subscribe and get notified for
any upcoming new episode. Also do check out and follow
technology. No social media channels on
LinkedIn, Twitter and Instagram everyday.
I post nuggets of wisdom from each week's episode, and I share
them on those social media channels to help Inspire us to
get better each day. And if you'd like to make some
contribution to the show and support the creation of this
podcast, please consider joining as a patron by visiting
technology, not deaf. / Patron. I highly appreciate any kind of
support and your contribution would help me towards
sustainably producing this show. Every week for today's episode.
I am happy to share my conversation with Helen Scott
Helens. Got is a technical writer and
Java developer Advocate at jetbrains.
She has over 20 years experience in the software industry, in a
variety of roles, such as a developer, technical writer
product owner and advocacy. These days whether you are
producing mobile applications software as a service, apis
software platform, or open source project.
We all kind of agreed of the importance of a good technical
documentation and it is, sometimes the most underrated
part of a software delivery of an times.
Its importance is only realized when users are having problems.
When using your software as such the role of a technical writer
is becoming more and more important, especially for a
software produces. Seeing company and team and not
just technical documentation. Technical writing can also cover
technical content, such as blog posts tutorials.
Social media posts tweets, Etc. In this episode Helen and I
discussed many things about technical writing such as the
technical writer role, definition, the traits of a good
technical writer and how to create a good technical content,
including a few gotchas that. Our technical writer needs to be
aware of Helen, also shared some Of her content creation and
sharing tips and hacks based on her popular blog post, which you
can find on her website as a new content creator.
Myself. I personally found those hacks
really useful to help me becoming a better content
creator going forward. Another thing that Helen shared
with me is the concept of community mentoring, which was
quite new to me before this conversation.
And she explained how having Community mentoring program, can
be helpful for the mentee, the mentor and the See all together.
And if any of you are interested in this kind of program and
would like to find a Community member and that you think I can
help you. Please feel free to drop me a
message and I'll be more than happy to discuss with you.
To see how I can help you based on my experience and knowledge.
I hope that you will enjoy this great episode.
Please. Consider helping the show in the
smallest possible way by leaving me a rating and review on Apple
podcast and other podcast apps that allow you to do.
So those ratings. Reviews are one of the best ways
to get this podcast to reach more listeners and hopefully the
show gets featured on the podcast platform.
I'm also looking forward to hearing any comments and
feedback on the social media or you can also directly send to me
at technology. You know, that death / feedback.
So let's get the episode started right after our sponsor message.
Are you looking for a new cool swag package, you know.
Now offers you some swags that you can purchase online.
These swags are printed on demand based on your preference
and will be delivered safely to you all over the world where
shipping is available. Check out all the cool swag is
available by visiting technology.
No dot f / shop and don't forget to break yourself.
Once you receive any of those tracks.
Hey everyone, welcome to another episode of The Faculty Journal.
Today. I have a special guest with me.
She is actually an expert in technical writing.
She's been doing this for a number of years.
Interesting enough, her background started from a Java
developer background, and she'll probably tell a story why she
switched to technical writing and intersecting with Java again
lately in jetbrains. So her name is Helen Scott.
So Helen, welcome to the show. Very happy to see you here.
I Henry. Thank you so much for having me.
I'm really looking forward to this chat today.
Thank you. So Helen to introduce yourself
to the audience. Maybe you can tell us a little
bit more about you. Your career, any highlights
turning points and things like that.
They're worth to share for everyone.
Sure. It's been a little bit of a
warranty journey. I started off when I kind of
typical path with a degree in computer science and we did
Joffrey University. So we're talking late 90s now
and Java was very new at the time.
So I graduated from University and I was quite young and
arguably quite naive and I went straight into the first job that
seemed to be the right job, which was Java programming and I
had a really hard time and I really struggled I actually left
that job after I think it was less than a couple of years
because I just wasn't having a good time.
So I left, I went out and took a little bit of a career break.
I went out to South Korea and taught English for a year
because I didn't know what I wanted to do with my life.
Whilst I was out there. Some friends said, why don't you
try technical writing? We think you'd be good at it
and, you know, friends always have your best interest at
heart, don't they? So, I listened to them and they
were right, so I came back. And I took my first job as a
junior technical writer up in near Oxford and I wasn't there
for very long. I Was Made redundant, but it
really taught me that I felt at home with technical writing.
I could create content. I could still work in software
development that I was really passionate about.
But I was creating content that I, well, a felt like I was good
at and be really enjoyed. So I moved on to various well,
two or three, technical writing careers.
After that or two. Writing roles, I should say
after that the settling down eventually in the north of
England throughout that time. I really kind of built up a
passion for what I believed to be assets.
I suppose of a good technical writer.
So working across software development teams, really
focusing on the relationships that you have with the
developers. Because, you know, two hours
before release the last person they want to see as a technical
writer. I focused on making sure that I
was thinking, like an end user. So I was kind of a proxy of the
end user, so I was thinking, okay, if this is complicated
Dated, then the end users probably going to find it
complicated equally. Always making sure that I
downloaded the night leaves and poked it like the testers poked
it, obviously, they're way better at the poking that I was.
But from the point of view of a user, some would come along, and
go. What does that button do and
then go home that button? Didn't do what I expected it to
do. That's interesting and feeding
that back and raising a bug. So being a very fully fledged
and functioning member of the development team, whilst
creating this content. I stayed doing that till 2019 so
fairly recently identified. Took an internal pivot to a
product owner role because for various reasons, I decided that
I wanted a little bit of a change and it looked fun.
And I did that role and I enjoyed that role.
It taught me, what I'd liked, but it also taught me what I
missed and what I really missed was creating content.
I also, in that role was only working with one scrum team.
I missed working Across The Wider Department, which I just
didn't see coming at all. I really missed that interaction
with a wider group of people. So we're up to March 20, 20.
We're into lockdown one Groundhog Day over here.
I then got chatting to my colleague.
Trisha G, who had known from University.
Actually. She encouraged me to apply for
the role at jetbrains as a Java developer Advocate.
And I said, but I haven't programmed in Java in 20 years
and she said, yes, but you have all these other skills that we
need in advocacy and you can learn the Java stuff.
You know, it's just a skill at the end of the day.
So once again, I To, and I applied.
And I got the job. So I now get to do all the stuff
that I did as a technical writer because I still get to create
all the content. It's just to a much, much wider
audience and equally, I get to work with the community rather
than just scrum teams in a business where it's like a
bigger version of that. And I get to pick up Java again
after 20 years with arguably a lot more life experience under
my belt that I perhaps had a kissing 90s and equally ever.
Very supportive team and Community around me.
So yeah, a little bit of a windy Journey, but they have it.
So I'm interested when I heard you said that your friend
initially advise you to go into technical writing.
So, do you know what your friend saw in you that they felt you
are a good fit for technical writing?
I think because these friends were friends that I'd gone to
University with and I had done very well in my end of your
assignment. I've got a first demand of your
assignment and I'd helped them with their Your assignments as
well and the same way that they'd helped me on the
programming front was like to me that stuff was relatively easy,
whereas programming might as well have been rocket science.
So I think because they could see that I Not only was good at
creating the content but I enjoyed creating the content and
I enjoyed thinking like the user and structuring it, how I would
want to read the content and making sure that it's correct
and it flowed nicely. So I think that I have a feeling
that was probably why they suggested technical writing.
So if we can go deeper into technical writing, first of all,
what do you think is the definition of technical writing?
Because these are so many people can write.
There are so many things technical, but what is the mix
between these two? As a definition?
That is an excellent question. I have a little bit of a
love-hate relationship with the job title.
Technical writing. I do question a lot.
What's technical about technical writing because you don't say,
I'm going to be a technical program error or a technical
product owner or a technical tester yet.
We have this Oddity of a technical writer, which I have
never fully understood myself. If I find it a little bit
strange, so definition of a technical writing or technical
writer. I would say, is somebody who is
just forget the word technical from an it is, somebody who
works with software development teams.
It is somebody who can think like a customer and Champion the
customer. Internally.
It is somebody who can pause. I'm not even going to say
technical information, just pause information from
development. It is somebody that can take a
bunch of inputs that come in at various times.
And at the Various levels. Pause.
What is important, pause? How that needs to be presented
to the user and then bring it all together into
customer-facing content. Alongside the other inputs such
as the voice of the company and any brand considerations that
you need to take into account. So, it's pretty a good
definition. I would say, like, you have to
think like a customer, first of all, because the consumer of the
content definitely is the customer or the customer facing
side of it. And then, yeah, there's this
bridge between the development side and also the So let me talk
about technical writing content, write the content itself.
What are some of the formats? I mean these days, there are so
many different types of formats, right?
Yeah. Is there any specifics?
So they can be broadly split into two groups online and
especially call it offline. There are a number of companies
out there that are still reluctant to put their
documentation, you know serve it publicly facing the vast
majority of documentation that I created, as a technical writer
is still behind not pay walls, but I've actually sent to the
customer directly. It's not publicly available and
there can be a number of reasons for that, especially in certain
industries such as defense or customers are nervous to put
that kind of collateral online, because it may give competitors
an advantage. That's another one that I've had
leveled at me and I've pushed for it to be available, my take
on, that is from a documentation point of view.
If you're going to write good documentation and you want it to
be helpful to the user, you have to remember that if a user is
even reading documentation that a technical It has produced
they're probably already annoyed.
There are a couple of exceptions to that like release notes, but
they are probably already annoyed because I don't know
about you, but even me as a 15-year technical writer
background, I don't want to read the documentation.
If I can't get it to work. I'm annoyed.
The software's failed. May I don't want to go and click
F1. No, I'll click every other
button first and then I'll sulk and I'll click F1.
I think when you put yourself in that mindset and you think like
the user and then the user Has to jump through another hoop of
authentication, to potentially. Look at the documentation.
That's really frustrating for them and not a great user
experience. And ultimately, the
documentation is part of the software.
So you have to consider the whole user experience that
they're having with your software.
In fact, especially includes the experience they have when they
need help, right? For me personally, I would
probably not go into the documentation.
First of all, I would just go to Google or stackoverflow.
Hopefully, the technical document itself is the first,
Top pages on Google, right, if something hasn't hidden it.
Yes, right. So tell me in the first place,
right? Your friends, identify you as a
good technical writer, but people out there who are doing
some sort of role as a technical writer as well.
What do you think? Are some of the good traits of a
technical writer? Is it more like the language
writing formal English and things like that or customer
empathy that ever makes inquisitive is the first one
that Springs to mind you have to want to poke.
Things. You have to have a desire to
find out how stuff works. You have to want to learn.
You have to want to Champion the customer.
You have to care, fundamentally, you have to care about the
software. Because if you yourself, can't
figure the software out, or don't understand how the
software is working. And I mean every single bit of
it, then how are you going to document it correctly?
How can you possibly get enough information into the
documentation for the customer if you yourself, do not
understand what's going on and that?
Is incredibly hard at times because there's some, certainly
some enterprise software that I've worked on that.
I've frequently been like, yeah, I don't get it and I've said
that and I've gone back and got ya now.
I still don't get it and develop as a sat down with me for hours
and explained. Yeah, but it's still not
completely clear. I'll be honest.
So that brings me to my second point, you have to have
excellent communication skills because you have to put the
whole puzzle together. And let's say the puzzle every
single day of that's working on. This has a piece of the Puzzle.
They know that piece of puzzle, inside out, but you have to go
and make the jigsaw. You have to get all those
pieces. You have to put them together,
and you have to understand each one at a level, that is good
enough for the customer. You're never going to understand
it to the level of the developer.
I expect because they are going to have an additional
understanding at the code level. That is not relevant for the end
user. But you yourself need to pull it
all together. You need to be inquisitive.
You need have excellent communication skills.
You need to have good relationship skills because
Developers are busy people. So it's something that's quite
interesting. I certainly found throughout my
career when you're working on a it doesn't matter.
Whatever size of Team. It is everybody's different and
everybody likes to be approached in a different Manner and
everybody likes to manage their time differently.
Some developers don't mind if you, this is obviously
pre-pandemic. They don't mind if you just rock
up at their desk and say can I just ask you a quick question,
please? Because I'm a bit stuck.
They don't mind that at all. Whereas other developers much
prefer a more formal approach. Roach of get half an hour of
your time next week to have a chat about this feature because
I don't really get it. You have to be very comfortable
saying, I don't get it. That's probably a statement.
I've said a lot in my career. You have to be very good at
stakeholder management as well. So again, as a technical writer,
your glue, you're in the middle of a process to one side.
You've got software, you've got development teams to the other
side. You've probably got a bunch of
stakeholders that have a vested interest in making sure that
what you create. It's good and it's correct as
what the business wants. So, over here, on this
stakeholder side. You might have people in the
product team, who want to check your documentation.
You might have other people who have a more strategic view of
the development Direction, maybe people who work on the
architecture, maybe product managers who may want to review
documentation. I've even had people in
marketing wanting to review documentation.
So you have to manage all their timelines as well, because as we
all know, software, timelines are quite an interesting beast
and you're just a A cog in a very very big wheel at that
point. So you have to keep an eye on
the wider landscape of where's everything tracking.
Are you tracking? Okay.
I'll be in a situation where actually you need to be raising
a risk and saying this is a massive, massive change late in
the day. Therefore.
There's a risk that the docs aren't going to be done.
What do you want to do about that?
So you have to kind of be everywhere all at once.
No everything all at once. But it's all about knowing it at
the right level. You're not going to be able to
Deep dive to That's why you've got a whole team working on the
product. But you need to have a decent
understanding across the board, to be able to document it
communicator, and make sure that it's what is going to be best
for the customer. So it seems like a lot of skills
that are required and I like in the beginning you mentioned,
when you did your technical writing.
Sometimes you download nightly builds or the Night Live
software version. And also you mentioned about
when you describe about the role itself.
The role is expected to have an understanding of of how you use
the system as a user point of view, technical product can be
many things, right? Could be just a software
software service or it could be a platform or it could be an
open source project. Does it mean that the technical
writer also need to have a technical background?
In a sense that they are able to use the product?
And to n-no this for me falls into the same bucket as learning
Java or learning any technical skill.
It's a skill. You can learn it.
It's one of my frustrations about seeing job specs like need
to be an expert in this this This this and this you can learn
that stuff. It's great.
If you're an expert in some of it.
I'm sure that will really help your application, but it goes
back to the notion of a technical writer technical
Writers. Come from all walks of life.
I've seen technical Writers come from computer, science,
backgrounds, and programming background such, as myself from
testing backgrounds, from English, language, backgrounds
from straight up communication backgrounds.
I've known a technical writer transfer in from a civil servant
a government role here in the UK.
Anybody who is passionate about communication and creating
content that helps the user can be a technical writer write.
So we have mention about the role itself.
So how about the content itself? Is there any good element of a
good piece of technical content? Make sure it's cracked.
I tell various sarcastic jokes as a technical writer.
You won't hear anything about your documentation and less.
It's wrong. Believe me, then you'll hear
you'll never hear if your Communication is correct.
But if it's wrong, you'll hear about it.
And you'll hear about it from a number of sources, which is both
great because it means, okay, someone read it.
And they're like, yeah, it's wrong.
So, try and try and make sure it's correct.
And it goes back to what I was saying about.
You have to learn everything to a good enough level to be able
to document it for the customer. You are only human.
You will make mistakes people reviewing, your documentation
will make mistakes. Ultimately.
It's your documentation. It's on you.
You'll make mistakes in the same way.
So, software has bugs. It's just the way of the world.
So try and make sure it's correct, except it won't always
be correct documentation rots really quickly as well.
So especially documentation that is not online because if you are
still some companies are putting out PDFs as their documentation.
As soon as you release that documentation that PDF leaves,
it's at date and I know that sounds awfully brutal and a
little bit dramatic but effectively it is it's out of
date. You can't update that PDF.
I sitting in their inbox, you're done, and you're especially
done, if it's wrong. So I would say, if you are still
creating PDF content, try and move to some sort of online
content because it gives you much more control to updated.
Good documentation. Also make use of layering.
So information density. I think is a really important
Point here and it goes back to. If the customer is reading your
documentation. They are probably annoyed.
So you need to give them the right documentation at the right
time and no more. I mean, you may know lots more
about the product and you may be very tempted to say also,
there's this really cool feature.
If you do blah, blah blah, they don't care.
Just give them what they want to know when they want to know it.
What you can do though is you can take advantage of layering
so you can layer your content. So you can use things like links
and signposting to say if you want to find out more about this
super cool feature that I really like click here and that allows
your reader to explore at their Pace on their time scale.
So that's a really useful technique.
Another one. I think it's the difference
between what's really obvious and what's valuable, and it's
very easy. And I know I fall into this trap
in the past. It's very easy to document the
obvious and sometimes you do that because you want the
documentation to be complete. And even if one feature is
really, really, really really obvious you as a technical
writer think, but it's on the page so I should put it in the
documentation because there's a thing about completeness going
on, but equally if it's really obvious you don't need to
document it. And it takes, I think it took me
quite a lot of experience before I kind of realized.
I don't need to document that it's okay.
Valuable versus obvious. The one that comes to mind and I
think will be most relatable is frequently asked questions.
It's drives me mental. A good frequently.
Asked questions are very, very rare.
So if you are asked to create frequently asked questions, make
sure they're the right ones because there is nothing more
infuriating. For user when they're going
through a process and says, have you checked our frequently asked
questions and they have a question and it's not there.
So really think long and hard about creating frequently asked
questions go to your support department and say what
questions do you get asked? Because they'll say ha actually
we get asked x y, and Zed quite often, but we never get asked
this one. Okay, take that one out and put
X Y and Z in. Give your users a Fighting
Chance because if your frequently asked questions are
not, Frequently asked questions. You're going to really annoy
your customer base. So make sure they're correct.
Make sure they are valuable and you're documenting the right
things, use your company's brand voice.
That's one that most tech writers, usually, just have to
fall in line with, it doesn't need to be dry.
Not all companies have dry branding but be very careful if
you're going to deviate too far from that.
Especially as you know, something like slang definitely
doesn't translate. Well, so always consider
translation costs, especially if you're a global company.
Even if you're not a global company consider translation
costs consider how readable your content is as well.
Remember the language that you're writing in everybody
reading your content that might not be their first language.
So don't go and create documentation that is littered
with words that are not in common usage.
It's just not cool. Make sure it's up to date.
You signposting, make sure it's not muddled and confused.
I've seen some documentation that's just muddled and
confused. I was going to say use headings.
That's very print-based, but you can Do that with online based as
well structure, get a pen and paper, work out, how you're
going to structure the documentation, especially if
you're in the privileged position of creating the
documentation from scratch, which often you are because
technical writers are not the first role that most startups
think of. So, they go home at some point.
We need a technical writer and then this technical writer comes
in expecting to work on documentation and gets, told
yet. There, isn't any documentation,
you're creating it from the ground up and that can be a
pretty fun as well as slightly stressful Journey.
As you were sharing about the correctness and also the FAQ
part, right? So I myself personally could
relate back to some of my previous experience trying to
find out Solutions. But actually yeah, the document
is not complete. It's missing.
And also when I go to FAQ, there's nothing that maybe
stack, Overflow is much better place to find the solutions.
That's another probably Trend. I don't know whether this is a
latest Trend or not. I see that some technical
document or technical content that actually embed, some kind
of a technical capability. Most likely is that Like API
documentation where you can actually run like test this API,
you can put some HTTP parameters or even sometimes from the other
side which is from the library itself.
Whenever there's an error or something.
They could actually link out to a document outside.
Maybe it's online or something like that.
I think that is kind of like a good experience, especially from
development point of view. What's your take on that?
I like it for the exact reason that you just said, it's a good
experience from a development point of view.
And at this point you're the end user.
So if it's a good Surprise for you, then as far as I'm
concerned, it's a good thing. Maybe that's what a technical
writer, is anything that makes the Journey of the end-user
better. And more joined up, has to be a
good thing. Again.
If there's inline documentation, certain products, use inline,
documentation a lot. The little question marks,
you'll see on certain web forms or interfaces.
They could be incredibly powerful because it goes back to
what I said, a little while ago. It's the right amount of
information. We've only got a little small
space. Fit it into at the right time
because the question marks next to the field that they want to
look up and know more. And if you want more, you can
put a little hyperlink in and say here's where you find out
more information. But yeah, techniques like that.
Anything that can lower that barrier between or even take the
burial way to the users, not annoyed because at that point
they're just like can I just confirm that?
This is what I think it is and if the answer is, yes, you have
averted user crisis. You have averted, 10 minutes of
cruising along stack Overflow. You have given them.
You've Elevated what they thought or you set them on the
right track, and you've done it without really interrupting
their day. So good job.
So in your personal point of view, maybe you can give us some
examples of great technical documents may be from a brand or
from an open source project as an example for us to refer to.
So I'm not going to do that and I'll tell you why I gave this a
little bit of thought and I decided that actually I was
going to be really true to myself.
I'm going to name one company that I think have great
technical documentation. Asian, but I think it's a bit of
a cop-out and that companies madcap flare while madcap the
company because they create madcap flare, which is a very
common authoring tool that I absolutely love using.
So their documentation is very, very good as you'd probably
expect making a product for technical writers.
They have a very harsh audience in that respect.
But when I gave this some more thought I realized that to be
true to myself and you said it a number of times already on this
call Henry documentation. That is potentially the most
value is often crowd-sourced. And it is the likes of stack,
Overflow. And I thought to myself, why is
that? And I realized because
everybody's different, everybody's experiences are
different and everybody has a unique way of approaching a
problem. Many of us might have the same
problem. Right?
But we all have slightly different operating systems,
slightly different tools. How many cups of coffee we've
had very, and we come at the problem from a slightly
different angle and we present it in a slightly different way.
So I think That's why things like stackoverflow.
Well, sometimes incredibly messy, and frustrating, and you
sit there going. How could no one have asked this
already? I think it's why they are so
valuable because you have a huge crowd Source pool of information
of both challenges and answers. The fact that people though
we've mentioned it so many times in school.
It works. I've used it myself and that to
me is a very underrated source of great technical
documentation. It doesn't need to be Kind of
Perfect. Polished pairs are amazing
online, documentation. It can be this crowd sourcing
and he just goes to prove that. Everybody can be at some level
of really great technical writer in quotes.
They can be because they've gone out there and they've posted
that and look at the community and they step up and they go.
Here's an answer to your question.
So, I mean, like, I've seen it in multiple open source
projects, but I'm not sure in terms of product companies and
things like that. Could it be that this will stop
a new trend of a crowdsource way of improving the documentation
is like, oh, Open source project, where you can raise
pull request. Everybody can make revisions
even typos on things like that. Is it gonna be like a trend for
product companies to do that in the future?
I think it might be it's not as easy as it sounds, as anybody in
the development world knows. It's like, oh, yes, let's just
open source that. But there are companies out
there that are starting to do this and it kind of shifts the
technical writers role. Perhaps, from a sole creator of
content, more to a maintainer of open-source content and Quality
gate. But I think there are a lot of
benefits to potentially be gained from doing it this way,
you know, if you've got a customer especially if you're
creating content, perhaps a developers using and I saying
this is wrong or there's a typo, or how about can we add this
piece of information? They can go in and go, you know
what, I'm just going to create a quick pull request and that
process is nice and easy. It's open source.
It's on GitHub. There's no special tool.
They need to run it locally. They can just create it, create
the pool. Requesting technical writer can
go. Oh, that's great.
Yes. Well, we'll bring that in.
So, you've got documentation that is very current is very
up-to-date. There is obviously an onus on
the team. Maintaining it to make sure that
the content going in is of high enough quality speaks to the
brand voice, but I think we are seeing a definite Trend in that
direction. It's just there is a hit on his
hit on structure because if things are a free-for-all, yes,
stack Overflow is amazing, but it's also free for all.
So it's a lot of duplication. And it would take a lot to clean
up stack, Overflow. Shall we say?
But I think there's some definite wins to be had with
open-sourcing documentation. For sure.
So, speaking about product documentation.
I've seen in multiple different products as well.
There are some common type of contents like for example, quick
start tutorial or maybe beginners concept and advanced
concept and things like that. Maybe prompt your point of view.
What are some of the good contents that our product
documentation should have like four?
Common People. Another good question.
So documentation that I'm particularly passionate about
that. I think goes across the board.
Our release notes, good release notes done.
Well, are very, very valuable. So, when you update a piece of
software customers want to know if their bug was fixed,
especially if they're the people maintaining the upgrade on the
customer site, they want to know other bugs fixed.
What else changed, you know, especially if it's not just a
bug, fix, what changed? What impact could it have on
their environment? They need to be clear.
They need to be They need to be not fluffy.
This is one of the blog's I wrote on the app, release notes,
but on your phone, when you update a nap, some of the
release notes are really good in that, they say this bug was
fixed. That bug was fixed.
We made changes to this. We've improved the performance
of that. Other thing over there.
I think they're just being a bit cute and fluffy when I say this,
but some of them are like, we fix some stuff to make stuff
better, and I sit there thinking, but that doesn't tell
me anything. That doesn't tell me how you've
changed this software that interacts with my phone.
And with me, everyday, I have No idea what you've done and I kind
of feel a little bit frustrated at that point because I want to
know what's changed. But I know when I have this
conversation with my friends, the answer I get is we don't
care Helen and maybe they're right.
Maybe that's just me that I like and respect.
When somebody has put the effort into telling me what change has
been made to an application that I use.
Equally, I totally admit, I don't read all the release notes
unless it's an app that I am particularly invested in or I
have raised a bug report for Yeah, release notes are probably
the most red piece of technical documentation.
That's technocrat, reduces because unlike the rest of the
technical documentation. You don't read release notes.
When you have a problem or you're annoyed, you read release
notes because you want to know what's in the new release.
And you want to know, if there's any gotchas to installing it or
are there any known issues again?
Knowing issue should go in the release notes, other types
content types. You've got your standard product
documentation, which is pretty much a catch-all for everything.
Again, we've spoken about Aiming to get that online.
So it doesn't rot as quickly and you can keep it up-to-date.
Frequently asked questions we've spoken about.
Please make sure they are the ones that are frequently Asked
tutorials again the kind of come under product documentation, but
with tutorials, the most important thing that I would
recommend is make sure you've tried the steps out yourself.
I recently didn't do this before.
It was actually a Blog, that's got a tutorial in and I sent it
for review with an assumption in and I didn't try out and it's
wrong and thankfully it's not gone live and I've been kicking
myself. Ever since.
So make sure you've tested the steps out because if they don't
work on your machine, they're definitely not going to work on
someone else's machine. Make sure you've considered
deviations like different operating systems or different
configurations. Make sure you thought about that
kind of stuff, especially when you're writing tutorial steps.
Because again, if a customer has taken a proactive step to follow
a tutorial, right? That's not reactive thing.
That's a proactive step, and the steps don't work.
You've got an annoyed. Customer and this time, they're
not over the software. They're annoyed with the
documentation. So, try and make sure they work.
I have recently started creating blog posts both professionally
and personally, they're an interesting one for me and I've
struggled a little bit to switch my mindset from technical
writing to personal writing because stuff that I put on my
personal blog. I have to switch off my inner
technical writing now and type more like me, so I have a more
informal way of typing in the same way that we all have a more
informal. Speaking.
It's slightly more formal for professional blog posts,
obviously, but it's a different form of writing.
Because certainly with the personal writing, you don't have
to adhere to any sort of company brand.
It's your brand. It's however, you want to put it
across. You can also bend the rules on
structure as well. You don't need to be quite as
structured with your signposting.
You can tell more of a story. You can be much, more story
focused, especially on personal blogging.
I find a lot of the blog's that we do professionally for Again,
we try and step through a process, especially if we're
blogging about a recent screencast or something.
So it's very sequential. So now your code will look like
this and these are the steps that you need to follow.
And these are the files that you need to change.
So again, it's more story focused than perhaps technical
writing with technical writing. You're documenting a piece of
software. You're documenting
functionality, rather than with the the blog post that I'm now
doing your more documenting a flow, a story, a process, a
task. And yeah, recently branching
into podcasts. So they're fun.
This is my second podcast session that I've done and well
so far. I'm learning Prep, Prep is good.
Have a good, think about how you want to answer some of the
questions especially, if you're somebody like me that sometimes
trips up, over my words. Cool.
So that's another thing that I find in not many companies, but
certain type of companies that actually create a really, really
good technical documentation or maybe blog post technical blog
post. That becomes like they're part
of Of the brands. They increase their awareness
and people just like them as such, right?
The brand becomes stronger and stronger.
Maybe people would even want to work with them simply because
what they provide as part of the content is really, really
marvelous and there's like a strong branding and advocacy
there. Do you think this would be a
good strategy for companies to invest on, especially to a
higher Talent, you know, like to attract talent to work with
them. My answer on that one.
I think is it depends. It depends so much on the
company and the Act and what kind of talent they're looking
to attract on the face of it? It would be very easy to say.
Yes. Absolutely.
I can't see any downsides, but there are some companies that
just wouldn't work for and they wouldn't want to necessarily
attract the kind of talent that would attract, if that makes
sense. So I think that is maybe more of
a marketing branding decision if they want to present themselves
in a certain way and it's going to work for them then,
absolutely go for it. I'm not sure it would be a vital
for every Every company I think there's probably a cultural
element to that as well. Don't what might work in one
country wouldn't necessarily work in a different country.
That's just a suspicion. But yeah, if the company is
willing to try it then I think it could be a very valuable tool
for them. So Helen I saw you also had a
blog post about community mentorship.
So personally when I view it is it like any other kind of
mentorship or what's the take on the community side?
Maybe you can share a little bit about what do you mean by
Community mentoring? Sure, so that blog post came
about because of a conversation that I had with somebody bury in
the London Java Community because he said that there's a
community mental scheme and it's run by Rick works.
And I said, but I can't have a community Mentor yet because I
don't know enough. And I'd be wasting their time or
words to that effect. And he said, but you can we have
people within the community who are willing to work with people
such. Yourself and impart their
knowledge and I kind of went away and thought about it for a
bit and did end up getting not one, but two mentors.
And it really got me thinking, what is a community Mentor?
Because I use the frame Community Mentor because I
wanted to burst it to find it as somebody that is in a community
in a community, that you also are part of, and that you want
to grow yourself in. But a mentor in terms of the
relationship for me a community Mentor.
Is there somebody in the community?
They are somebody who potentially has been in the
community for a while. While they might have attributes
such as a large platform on social media, like numbers of
Twitter followers, for example, they might be somebody who
regularly works the conference circuit.
They might be somebody who has a specific, technical skill set
that you're keen on improving yourself, but they are people
within the community who are willing to work with you and
ultimately give you a seat at the table.
We need help. We all need a little bit of
support and mentoring and are leading at times.
So they might be somebody who just checks your content and
says, yeah, I really like this blog post, great job or they
might be somebody that reviews talks that you've given and
says, okay. Yeah, that took about two
minutes 51. Instead of saying that maybe
change it to this, because of these reasons, or they might be
somebody who is willing to co-present with you at a
conference that in itself, especially if they're a really
well-known speaker that can do wonders for your career.
If they're willing to say, you know, what, come on up, come and
present. It's me, because getting on that
stage for the first time is really, really terrifying.
They might be somebody who is willing to use their social
media-based to elevate your content.
So if you're blogging about something that's in their sphere
as well. They may be willing to retweet
that blog for you and say Reach Out meet these people.
So there's somebody that is in the local community.
They have offered to help. They have a set of skills or
some knowledge that they are willing to impart.
They are open and honest. About that.
No money should exchange hands in my view.
They are just people who want to help you.
They are people in the community and just because you have a
mentor, does not exclude you from being a mentor as well.
I am entering a couple of people as well at the moment.
So one in terms of their writing and one just in terms of their
creation of content and working within the community and
building up their confidence. That's a really interesting
Journey as well because it's not just used the mentee that grows.
You can grow as a mentor as well.
You can learn so much about yourself by doing it.
So, yeah, that's what a community Mentor is to me.
First of all, I mean, I must admit.
This concept is pretty new to me.
What I know about mentoring normally is from within the
company itself. Like you have some seniors maybe
from other departments. You can have a mentoring
relationship or sometimes. Also you join like a mentoring
group. It's a specific group just to
match a mentor and mentee and but this but this community
mentoring seems pretty new to me and it's very interesting that
you said that the mentor should come from a community Maybe.
They are more influential so to speak.
They have a large audience or they have a great technical
skills being in a conference and things like that.
So, for people like me, or many people out there, right?
How should they find Community Mental or in the first place?
Should they get a Community member?
So, in the first place, if you're trying to decide, if you
want or need a community Mentor, identify, what is it that you're
looking to improve? Is it a particular skill.
Is it more confidence in public speaking?
Is it more confidence with writing blogs?
Is it something else entirely ask yourself?
If you've got the time as well, because you are going to be
entering into potentially a professional relationship with
this community mental, whereby, they're going to expect rightly
a commitment from you. So it's not unreasonable to say
can I give that commitment? Can I give that time?
Then? Look at the communities that
you're part of. Do they have a mentorship
program if they don't don't be afraid to ask.
Is there anybody willing to Mentor me in this and set your
expectations up front, you know, say these are my expectations.
This is what I'm looking for. It's a professional
relationship. So expectations must be met in
the same way expectations for the first meeting must be met.
This is actually in the blog post that you're referring to.
So one of the other Advocates that I work with, actually wrote
that section. He sets out in the blog, a very
clear framework for what that first meeting should look like
because ultimately it's a case of try working with this person.
It might work out, it might not and there's no shame in saying
actually. That's not going to work out
because it ultimately needs to be a relationship that is built
on trust. A mutual respect and if you
don't have that, it's time to move on.
So yeah, it's a case of find out.
If there's a mentorship program, if there's not State your
expectations and ask for one special, you can go to the
leader of the community and say, this is what I'm looking for.
Is there anybody out there that is perhaps willing to help and
support me. So, how about from the mental
side of thing? So if you are part of a
community, maybe up skills. Why do you think these people
should offer mentoring for other people in the community as well?
So why do I think people should volunteer to be a mentor, right?
Yes. I don't necessarily think that I
think for some people they want to be a mentor and they are
particularly passionate about lowering the barriers to entry
in the community for certain things like public speaking or
like creating more Community content.
Some people don't necessarily want to be mentors and that's
completely fine. It is not for everyone.
They may not have the time or it may not just That's okay.
That doesn't make them a bad person or anything like that.
It's just a case of some people are particularly passionate and
particularly good. Elevating other people in the
community from what I've observed in communities.
There are a lot of those people and there are people that have
the time and have the inclination.
So they also understand they want that to a relationship
because they understand how they themselves as a mentor will grow
and learn from it as well. It is not.
And I can't stress that enough. It's not a one-way thing.
It sounds like you've got this mentor.
And this mentee that it's going to be a one-way flow from the
mentor to the mentee. And it's not and it shouldn't
be, there's definitely a flow the other way because that
mentee can teach that Mentor a lot about themselves.
They may have forgotten what the journey was like 20 years ago
and you've got this person starting out on a very similar
journey and they may want to just help them and say, you
know, what, don't fall over that.
Don't trip over that. Let's look at that and let
Introduce you to these people. They are just people that want
to give you a seat at the table. There's another quite brilliant.
Post that you have lately as well, which is about the hex for
Content creation and sharing. I know you have a lot of points
there. Maybe if you can share some of
your favorites from those hacks for people who want to produce
content or want to produce a better content.
So this talk came out of a blog post that I wrote initially,
that was just seven hacks. And now the talk has got 17
Hacks in. So that just goes to show.
I'm not going to go through 17, but I try and picked up five.
First one is when you're first starting out, just get into the
flow of producing content and Publishing it because no one's
going to read or watch it. Anyway, especially if you have a
very low Twitter account, I know it sounds rude but it's true.
It's just a case of getting content out there and I know
this because I completely panicked about publishing.
My first blog, a little while ago now, and my good friend sent
to be. It's fine.
Helen, don't worry. No one's.
Going to read it anyway, and I thought to start with well,
that's quite rude. Actually, they were right.
And it helped to give me the confidence to just put content
out there because it just gets you into that mental model of
create content published content and it stops, you overthinking
it. So yeah, that's one create
experience based content is another one.
So many people who are creating content or want to get into
public speaking. Say things like well someone's
already spoken about that or someone's already blogged about
That. And I'm like, yeah they have but
they have not had your exact experience.
And nor are they are going to approach it in the same way that
you did. So by creating experience based
content. No one can argue with your
experience. It's Unique to you.
And in fact, this speaks volumes, but going back to stack
Overflow. This is one of the reasons that
I think stack Overflow is so successful is because it's
experienced based content. Yes, there's a lot of
duplication, but people come at the same problem from a Of
different angles. And they all have different
experiences and different approaches to that problem in
different ways of writing it up on stack, Overflow.
And that's one of the values in it because when you're looking
for stuff, you might see ten answers, but only one of them is
going to be possible by your mind.
Only one of them. Are you going to be able to go?
Okay. Yeah, that one makes sense.
The other nine might as well be written in.
Jargon. So create experience, based
content, another one information density.
This one. In fact, your guests, my
colleague, Trisha Jesus. Excellent at this, when you are
creating a Blog, it works especially well in blogs.
Actually, if you referenced other content, when you created
that blog. So, for example, she's got a
Java rate, talk. If you are referencing content
such as numerous other blogs or technical articles or Java
specifications, just put all the links in there that you used,
because it allows the user in the reader to explore at their
own pace. And if they don't want to click
on the links, they don't have to, that's okay, but just put
them in there. Put as much information in there
in the same. When you're creating online
documentation, you're using the layering technique.
So you're putting information in that you're putting links in
there. And then you can drill down from
there. Another one would be don't
listen to the voices. These are the voices that set up
on one of your shoulders and they come out with rubbish.
Like you're not good enough. This isn't valuable content.
No one's interested. In this, they come out with
comments that are going to put you down and you're never going
to get rid of them completely. At least, I haven't managed it,
but you have got a bunch of little dudes on the other
shoulder and they'll say stuff, like you are good enough or
experienced is valid. This is useful.
It's just a constant fight going off on your shoulders.
So you'll never manage to not listen to them completely, but I
would encourage you to pop them in a little box, close the lid
and sit on the lid because they are not going to do you any
favors on the whole. So I'm now opt for.
So I'm going to limit myself to one more.
Don't let perceived lack of language skills.
Hold you back. And I mentioned this one because
I Worry about it, with my technical writing background.
I think if blogs got a typo in or if I trip over my words in a
podcast, then people are going to say harsh things, but it's
simply not true and the same is true for accents as well.
I get so sad when I hear perspective speakers say, I
don't want to speak because of my accent or you won't be able
to understand me and it's like, no, I want to hear what you have
to say. Your accent is beautiful.
And you already speak, at least, one more language than I do and
probably more. Which in itself is amazing.
So I would say, please please, please don't let that hold you
back, because people don't come to listen or worry about your
accent. They come to your talk because
they want to hear what you have to say, because your experience
is unique, and your knowledge is fascinating.
So share it. Thanks for sharing.
All these hacks, personally, as a content creator.
I could use some of your hex, as well.
So for others, who are interested to know more.
I mean, there are 17 0. So that means there are other 12
heck. Out there, I'll make sure to put
the links in the show notes and you can check it out yourself.
So, haven't we come to the end of this conversation before I
let you go. Normally I would ask all my
guests, this thing called three technical leadership.
Wisdom. So do you have any kind of
leadership just that you have found from your career to share
with the audience here. So my first one would be engaged
with and learn from the community.
They are an incredible group of people.
Many of them have walked the same path that you're walking
some Of them are behind you in your journey.
Some of them are ahead of you in the journey, but they all want
to help. I haven't yet found anybody
who's not willing to help in the community and that might not be
a full-blown mental just yesterday.
Someone picked me and said, you know what, your blog's looks
really funky on my phone. I'm not really sure what's going
on and they want to help and people want to support and want
to help you grow. So engage with them and learn
from them that be my first one. My second one is create content.
It is so beneficial to you it. You've spent your learning, you
don't need to be a technical writer to create content.
You can put it out there. You can share it with the
community. And guess what?
The community will learn and will grow as a result, because
you are helping other people, you are bringing your unique
experience and your unique Viewpoint, and it goes back to
stack Overflow. There might be those nine
answers, but somebody actually needs that tent answer, which
you can provide from your experience in your Viewpoint.
The third one is just to believe in yourself and believe that you
can learn things. So, your career may be windy.
It may not be straight line from computer science, Java
programmer for 20 years. That's great.
If it is good for you, you find what you love straight away.
You can learn stuff, you can fill in the blanks, but just
remember that you're amazing. And you have an immense amount
of value to bring. Well.
Thanks for sharing all this with them.
So Helen for people who are interested to learn more from,
you may be asking you to become the mentor or learn more about
technical writing where they can find you online.
Yeah. I'm on Twitter.
And Joe Scott think it's same on LinkedIn.
Same on GitHub. My websites also Helen, Joe
Scott.com. So, thanks.
Again. Helen for spending your time.
Looking forward to your next blog post, which I find quite
interesting. Thanks, Henry.
Thank you so much for having me. Thank you for listening to this
episode and for staying right till the end.
If you highly enjoyed, please share it with your friends and
colleagues who you think would also benefit from listening to
this episode. And if you're new to the
podcast, make sure to subscribe and leave me your valuable
review and feedback. It really, really helps me a lot
in order to grow these podcasts better.
You can also find the full show notes of this conversation on
the episode page at technology. No, the death website.
Cluding, the full transcript, interesting quotes, and links to
the resources and mentions from the conversation.
And lastly make sure to subscribe to the show's mailing
list on technology. No, the deaf to get notified for
any future episodes. Stay tuned for the next
technique Journal episode. And until then.
Goodbye.