#29 - A Guide to Technical Writing and Content Creation - Helen Scott

Episode Introduction [00:00:49]

Henry Suryawirawan: [00:00:49] Hey everyone. Welcome to another new episode of the Tech Lead Journal 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’re new to the podcast, know that Tech Lead Journal is available on major podcast apps, such as Spotify, Apple Podcasts, Google Podcasts, YouTube, and many more. And make sure to subscribe and get notified for any upcoming new episode.

Also do checkout and follow Tech Lead Journal social media channels on LinkedIn, Twitter, and Instagram. Every day, 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 techleadjournal.dev/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. Helen Scott 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 agree of the importance of a good technical documentation. And it is sometimes the most underrated part of a software delivery. Often times it’s 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 producing 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 a 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 posts, 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 programme can be helpful for the mentee, the mentor, and the community altogether. And if any of you are interested in this kind of program and would like to find a community mentor and that you think I can help you, please feel free to drop me a message, and I’d 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 Podcasts and other podcast apps that allow you to do so. Those ratings and 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 techleadjournal.dev/feedback. So let’s get the episode started right after our sponsor message.

Introduction [00:05:09]

Henry Suryawirawan: [00:05:09] Hey, everyone. Welcome to another episode of the Tech Lead 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 will 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.

Helen Scott: [00:05:41] Hi, Henry. Thank you so much for having me. I’m really looking forward to this chat today. Thank you.

Career Journey [00:05:46]

Henry Suryawirawan: [00:05:46] 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 that are worth to share for everyone?

Helen Scott: [00:05:56] Sure. It’s been a little bit of a winded journey. I started off on a kind of typical path with a degree in Computer Science and we did Java at university. So we’re talking late nineties 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 interests 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 B, really enjoyed. So I moved on to various, well, two or three technical writing careers after that or technical writing roles, I should say, after that. 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 is 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, then the end user is probably going to find it complicated. Equally, always making sure that I downloaded the night release and poked it. Like the testers poked it. Obviously, they’re way better at the poking than I was. But from the point of view of a user, someone come along and go, “What does that button do?” And then go, “Huh, 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. I then 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 miss that interaction with a wider group of people. So, we’re up to March 2020. We’re into lock down one Groundhog day over here. I then got chatting to my colleague, Trisha Gee, who I’d 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 listened, 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, but 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 than I perhaps had back in the nineties. And equally a very supportive team and community around me. So yeah, a little bit of a winded journey, but there you have it.

Henry Suryawirawan: [00:09:57] So, I’m interested when I heard you said that your friend initially advised 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?

Helen Scott: [00:10:09] I think because these friends were friends that I had gone to university with, and I had done very well in my end-of-year assignment. I got a first end-of-year assignment and I helped them with their end-of-year assignments as well, in the same way that they helped me on the programming front. I 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 was correct, and it flowed nicely. So I think that I have a feeling that was probably why they suggested technical writing.

Technical Writing [00:10:48]

Henry Suryawirawan: [00:10:48] So if we can go deeper into technical writing. First of all, what do you think is the definition of technical writing? Because these days, so many people can write. There are so many things technical, but what is the mix between these two as a definition?

Helen Scott: [00:11:02] 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 programmer 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. I find it a little bit strange. So definition of a technical writing or technical writer, I would say is somebody who, let’s just forget the word technical for a minute, 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 pass, I’m not even going to say technical information, just pass information from development. It is somebody that can take a bunch of inputs that come in at various times and at various levels. Pass what is important. Pass 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.

Henry Suryawirawan: [00:12:07] So it’s pretty 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 customer. So, when we talk about technical writing content, right? The content itself. What are some of the formats? I mean, these days, there are so many different types of formats, right?

Helen Scott: [00:12:30] Yep.

Henry Suryawirawan: [00:12:30] Is there any specifics?

Helen Scott: [00:12:31] So they can be broadly split into two groups, online and I suppose you could 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 paywalls, but effectively are 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 defence. 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 when 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 wanted to be helpful to the user, you have to remember that if a user is even reading documentation that a technical writer 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 me. 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.

Henry Suryawirawan: [00:14:10] Right. For me personally, I would probably not go into the documentation. First of all, I would just go to Google or Stack Overflow. Hopefully the technical document itself is the first few top pages on Google, right?

Helen Scott: [00:14:22] If the company hasn’t hidden it. Yes.

Good Traits of a Technical Writer [00:14:25]

Henry Suryawirawan: [00:14:25] Right. So tell me in the first place, right? Your friends identify you as a good technical writer. But for people out there who are doing some sort of a 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?

Helen Scott: [00:14:45] Bit of a mix. 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 gone, “Yeah, no, I still don’t get it.” And developers 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 dev 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 to have excellent communication skills. You need to have good relationship skills. Because those developers are busy people. So, it’s something that’s quite interesting. I certainly found throughout my career, when you’re working on a, well, 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, “Uh, 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 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, you’re 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 is good. And it’s correct. And it’s 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 your 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 little 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. Know 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 everything. 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, communicate it, and make sure that it’s what it’s going to be best served for the customer.

Henry Suryawirawan: [00:18:33] 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 nightly software version. And also you mentioned about when you describe about the role itself. The role is expected to have an understanding of how you use the system as a user’s point of view. Technical product can be many things, right? It could be just a software, software as a 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 end to end?

Helen Scott: [00:19:08] 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 you 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 backgrounds, 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.

Elements of Good Technical Content [00:19:59]

Henry Suryawirawan: [00:19:59] Right. So, we have mentioned about the role itself. So how about the content itself? Is there any good element of a good piece of technical content?

Helen Scott: [00:20:08] Make sure it’s correct. I tell various sarcastic jokes. As a technical writer, you won’t hear anything about your documentation, unless it’s wrong. Believe me, then you’ll hear. You’ll never hear if your documentation 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 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 software has bugs. It’s just the way of the world. So try and make sure it’s correct, accept 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 out of 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. It’s now 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 update it.

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 timescale. 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’ve fallen 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 it will be most relatable is Frequently Asked Questions. It 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 a 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, well actually, we get asked X, Y, and Z 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 is, 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. Use 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 at 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, “Oh, at some point we need a technical writer.” And then this technical writer comes in expecting to work on documentation and gets told, “Yeah, 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.

Henry Suryawirawan: [00:25:20] So 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 there. Maybe Stack Overflow is a much better place to find the solutions.

Inlining Technical Content [00:25:38]

Henry Suryawirawan: [00:25:38] There’s another probably trend, I don’t know whether this is a latest trend or not. I see there are some technical document or technical content that actually embed some kind of a technical capability. Most likely it’s the like API documentations, 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?

Helen Scott: [00:26:13] 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 experience 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 using 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 right amount of information. You’ve only got a little small space to 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, or you can put a little hyperlinking. 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 barrier away, so the user’s 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 a averted 10 minutes of cruising along Stack Overflow. You’ve given them. You’ve validated what they thought, or you set them on the right track. And you’ve done it without really interrupting their day. So good job.

Examples of Good Technical Doc [00:27:27]

Henry Suryawirawan: [00:27:27] So, in your personal point of view, maybe you can give us some examples of great technical documents. Maybe from a brand or from an open source project, as an example for us to refer to.

Helen Scott: [00:27:37] 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. But I think it’s a bit of a cop-out and that company’s MadCap Flare. Well, 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, the documentation that is potentially the most value is often crowdsourced. 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 vary. 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 Stack Overflow, while 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 crowdsourced pool of information, of both challenges and answers. The fact that, even though we’ve mentioned it so many times and it’s cool, 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 the kind of perfect polished “Here’s our amazing online documentation”. It can be this crowdsourced thing. And it just goes to prove that everybody can be, at some level, a 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.”

Open Sourcing Documentations [00:29:38]

Henry Suryawirawan: [00:29:38] 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 spark a new trend of a crowdsourced way of improving the documentations? Like open source project where you can raise pull requests. Everybody can make revisions, even typos, and things like that. Is it going to be like a trend for product companies to do that in the future?

Helen Scott: [00:30:00] 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 a 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 developer is using, and they’re 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 pull request. Then the technical writer can go, “Oh, that’s great. Yes. Well, we’ll bring that in.”

So you’ve got documentation that is very current. It’s 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 this head-on structure. Because, if things are a free for all, yes, Stack Overflow is amazing, but it’s also free for all. So there’s a lot of duplication. It would take a lot to clean up Stack Overflow, shall we say? But, I think that there’s some definite wins to be had with open sourcing documentation, for sure.

Structure of Good Product Documentation [00:31:31]

Henry Suryawirawan: [00:31:31] So speaking about product documentation. I’ve seen in multiple different products as well, there are some common type of contents, like for example, quickstart, tutorial, or maybe a beginner’s concept, and advanced concept, and things like that. Maybe from your point of view, what are some of the good contents that a product documentation should have? Like for common people?

Helen Scott: [00:31:51] Another good question. So, documentation that I’m particularly passionate about that I think goes across the board are 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 are the 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 concise. They need to be not fluffy. This is one of the blogs I wrote on the app release notes. But on your phone, when you update an app, 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 they say this, but some of them, they’re like, “We fixed 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 every day. 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. But yeah. Release notes are probably the most read piece of technical documentation that a technical writer produces. 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, known 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, that 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 I…, 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 it out and it’s wrong. And thankfully, it’s not gone live and I’ve been kicking myself for it 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 a 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 annoyed with 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 writer 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 way of 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 blogs that we do professionally for JetBrains, 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 blog posts that I’m now doing. You’re 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.

Blog Posts to Attract Talent [00:36:37]

Henry Suryawirawan: [00:36:37] Cool. So, there’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 posts, technical blog posts, that becomes like their part of the brands. They increase the 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 hire talent, you know, like to attract talent to work with them.

Helen Scott: [00:37:14] My answer on that one, I think is it depends. It depends so much on the company and the product 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 down sides.” 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 fit-all for every company. I think there’s probably a cultural element to that as well. That 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.

Community Mentoring [00:38:04]

Henry Suryawirawan: [00:38:04] 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?

Helen Scott: [00:38:20] Sure. So that blog post came about because of a conversation that I had with somebody, Barry, in the London Java community. Because he said that there’s a community mentor scheme, and it’s run by RecWorks. 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 as 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 firstly define 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, they are somebody in the community. They are somebody who potentially has been in the community for a 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 at 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 cheerleading at times. So they might be somebody who just checks your content and says, “Yeah, I really liked this blog post. Great job.” Or they might be somebody that reviews talks that you’ve given and says, “Okay, yeah, that talk, at 2 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 with 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 base 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 they’re 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 mentoring 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 you as the mentee that grows. You can grow as a mentor as well, and you can learn so much about yourself by doing it. So, yeah, that’s what a community mentor is to me.

Henry Suryawirawan: [00:41:25] 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. 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 mentor? Or in the first place, should they get a community mentor?

Helen Scott: [00:42:05] 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 mentor. 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 and 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. Especially if 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?”

Henry Suryawirawan: [00:43:38] So how about from the mentor side of thing? So if you are part of a community, maybe you have skills. Why do you think these people should offer mentoring for other people in the community as well?

Helen Scott: [00:43:50] So why do I think people should volunteer to be a mentor?

Henry Suryawirawan: [00:43:53] Right. Yes.

Helen Scott: [00:43:54] 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, 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 interest them. 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 at 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 two-way 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 me introduce you to these people.” They are just people that want to give you a seat at the table.

Hacks for Content Creation and Sharing [00:45:25]

Henry Suryawirawan: [00:45:25] There’s another quite brilliant post that you have lately as well, which is about the hacks 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.

Helen Scott: [00:45:42] So this talk came out of a blog post that I wrote initially that was just 7 hacks. And now the talk, it’s got 17 hacks since. So that just goes to show. I’m not going to go through all 17, but I’ll try and pick top 5. 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 count. 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 said to me, “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, publish 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 going to approach it in the same way that you did.” So by creating experienced-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. It’s because it’s experienced-based content. Yes, there’s a load of duplication. But people come at the same problem from a number of different angles, and they all have different experiences and different approaches to that problem in different ways of writing it out on Stack Overflow. And that’s one of the values in it. Because when you’re looking for stuff, you might see 10 answers, but only one of them is going to be plausible by your mind. Only one of them are you going to be able to go, " Okay. Yeah, that one make 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 guest, my colleague, Trisha Gee, is 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 8 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 and 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 way when you’re creating online documentation, you’re using the layering techniques. So you’re putting information in there. 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 sit 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. Your experience is valid. This is useful. It’s just a constant fight going off on your shoulders. 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 up to four. 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 tripped 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 prospective 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.

Henry Suryawirawan: [00:50:08] Thanks for sharing all these hacks. Personally, as a content creator, I could use some of your hacks as well. So for others who are interested to know more, I mean, there are 17 now. So that means there are other 12 hacks out there. I’ll make sure to put the links in the show notes and you can check it out yourself.

3 Tech Lead Wisdom [00:50:24]

Henry Suryawirawan: [00:50:24] So Helen, we come to the end of this conversation. But before I let you go, normally I would ask all my guests, this thing called 3 technical leadership wisdom. So, do you have any kind of leadership gist that you have found from your career to share with the audience here?

Helen Scott: [00:50:38] So my first one would be engage 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 mentor. Just yesterday, someone pinged me and said, “You know what? Your blogs look really funky on my phone. I’m not really sure what’s going on.” Now, they want to help. And people want to support and want to help you grow. So engage with them and learn from them. That’d be my first one.

My second one is create content. It is so beneficial to you. It helps you to cement 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 10th answer, which you can provide from your experience and your viewpoint.

The third one is just to believe in yourself. And believe that you can learn things. So your career maybe windy. It may not be a straight line from computer science, Java programmer for 20 years. That’s great if it is. Good for you. You found 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.

Henry Suryawirawan: [00:52:08] Wow. Thanks for sharing all these wisdom. So Helen, for people who are interested to learn more from you. Maybe asking you to become the mentor or learn more about technical writing, where they can find you online?

Helen Scott: [00:52:18] Yeah, I’m on Twitter, HelenJoScott. I think it’s same on LinkedIn. Same on GitHub. My website’s also helenjoscott.com.

Henry Suryawirawan: [00:52:26] So thanks again, Helen, for spending your time. Looking forward to your next blog posts, which I find quite interesting.

Helen Scott: [00:52:32] Thanks, Henry. Thank you so much for having me.

– End –