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.