81. Exploring Technical Documentation

Lenora: Wow.

Sejal: So, that was little adventurous for me. Then I moved on to telecom QA and software testing, which I did for a while. And I saw myself volunteering a lot on the side for human rights and agricultural rights. So, I thought of taking a break and see it full time, and see how it worked for me. And I did that. I joined, I took up a fellowship with Ratan Tata Trust in India, and that was a year long fellowship, which I then extended for another year on my own. And I traveled across the country and volunteered with different human rights movements, and grassroots movements. Understood the issues of rural India, and with the focus on public health, but try to understand how different issues connect with each other, and rural areas of India. And what are the solutions out there.

Sejal: It was like another life for me now. It's been 10 years since I did that. I did that for a while, two or more years. And then I took up freelance technical writing for some time, until I joined as a full time employee with Oracle and then Salesforce here. So here I am. After technical writing in Salesforce, I switched into product management. And now I work as a PM for our content engineering team. Focusing on developer documentation for the Salesforce developers.

Lenora: Wow. Okay. So, you started off with more of a volunteer life, where you focused on public health, and human rights and animal rights. And then from that, you just like, "Wow, okay! There's another lane that I could go into right in here where I could be more of a technical writer." Tell me more about that transition, how did you feel going into a whole new lane, and moving away from more volunteer work, and just going strictly into technical work? That's a big difference.

Sejal: Yeah, honestly I did not know about technical writing when I was in my earlier career of software testing. As an engineer I had no idea about this field existed. But I had a friend who told me about it. I was actually looking forward going back to my earlier corporate career, when I figured out that I was pregnant. And finding a job at that point, full time job, was not so easy, let's just say that.

Lenora: Yeah.

Sejal: So I was looking for alternate careers, and I had a friend who'd switched from developer to being a technical writer at that time. So, she actually told me what a technical writer does. And I did a couple of courses on it, understood how it's done. And I initially thought that, "Yeah, how different can it be? It's writing and it's technical. I know some of both." But I had to learn it. I had to unlearn some of the notions I had about technical writing, and understand what a technical writer is. What a technical writer does? Went through some of the documentation to understand it. Went into conferences, to educate myself more about it.

Sejal: I found that it was a different world altogether. When I was an engineer, I thought technical writing is all... What a technical writer would use, they would use, what? Microsoft Word, and those kinds of tools to write documentation. But that's not true, is what I discovered. Technical writers need a lot more sophisticated and complex tooling to get their work out. But it doesn't mean that it has to be a complex user experience for them. And that's what I also understood by being the writer, and now being the product manager.

Lenora: Wow. Okay. There's so much there. Okay. Let's break that out. All right. You talked about what is a technical writer? What is a developer documentation automation person, I'm guessing? Could you give more of a detailed explanation? Well, I don't want to say detailed... But however you want to tell us, about what exactly technical writing is, what does it entail, and more just about the field itself?

Sejal: Yeah. Let's do that by going to an example of say, Gmail, everybody uses Gmail I assume these days. How to use Gmail. It may be a no-brainer for many, but many would need help. So, if you are on the screen and using your Gmail interface, and you get stuck on the user interface. A technical writer would think of what to do so that you have help on the screen, and you don't get stuck. And if you don't get enough help on the screen, how to then redirect you to more help, which is the official documentation of the company. That is also written by a technical writer. But that is documentation not aimed for you and me, who are people who send or receive emails. But for example, inside Salesforce, we use Gmail, and we use entire G Suite. And there's a team of admins who configure what we can do, employees can do and they cannot do in Gmail.

Sejal: Those are the users who are admin users, and there is a special documentation that has to be prepared for enabling them. And technical writers would think of that kind of persona as well. Going forward we in Salesforce want to integrate Gmails with different sort of other faceless applications. And that integration would be done by developers inside Salesforce. But then it's a different persona than admin or end user. So developers would need to know how to use G Suite API's to do the integration, and open integrations with Gmail and Salesforce. So, how to enable that, how to develop user interfaces for that, and back end communications between two different systems. That would be documented. And that is a really crucial documentation. And that is an area that I work on. On how to enable developers so that they can empower themselves to develop these kind of systems, by using API documentations that companies can provide.

Sejal: And that is where you get into the automation areas. Where you need to document a lot of APIs for a system. And in this case, Gmail APIs to use, and how to use those APIs. And what are the parameters requests to send, or what is response that comes? A lot of things are coded, and that are designed via specifications. And that has to be documented, and writers wouldn't always get access to the code, or get an understanding of it. So, they need a simpler interface to document those by automating and fetching information from code specs and pulling into documentation.

Sejal: And then they have to develop code samples, examples around it, use cases, getting started, how to get access, and all those information for developers. And they have to document that. And that is an essential part of documentation, without which developers cannot function. If there's no documentation it means you have technically not developed an API. Because your end users wouldn't come to know about it. So, it's a very crucial piece of deliverables for developer-focused products. And if we treat an API as a product, you cannot have it without documentation. So, that is very essential. So, technical writers have to understand and put themselves in the shoes of these different user personas, and then design the documentation or content plan and journeys based on that.

Lenora: So, you talked about customer-facing, in-product help. Then you talked about actual documentation that's on a website. And then you talked about developer documentation. Which is three different lanes. And to me, I could see almost three different teams working on this. So, I wanted to know what does your team look like?

Sejal: My team is an engineering team, who enables writers to perform their tasks better in their day-to-day life. So, we are looking into developing tooling for writers that they can use to make their work easy, and documentation easy. But if you're asking about the writing team, yes, your guess is right. There are different types of technical writers, and there is an area of technical writing, which is very widely known as developer doc writers.

Lenora: Mm-hmm (affirmative) Okay.

Sejal: Those are very unique breeds, because it is not common for a technical writer to be a developer doc writer as well. There are very few writers in the industries who can be both.

Lenora: That's an interesting nugget, because it could help anyone who's trying to get into technical writing to understand which area they want to get into. And I'm guessing they will have to figure that out from, I guess, their interests? So, how did you figure that part out? Did you just say, "I'm already technical, I can do this." Or was it more, "I'm going to go into this field, see how it is, and then say yes or no from there."

Sejal: No. I tried to educate first myself to understand what technical writing is, what tools they use and the industry differently. I talked to technical writers, and went into conferences, I watched videos to understand most. I did online courses also to educate myself.

Sejal: My suggestion for anyone to get started is, you don't really need to be technical for being a technical writer. But having a good writing skill is a given requirement for technical writing. But you can learn rest of the things that is required for technical writing. Even for the developer doc writing, we have so many writers who work as developer doc, with no background in development. And they work wonderful well. So, I think it works out when you have interest area, depending on person's interest area. But it's all about the kind of learning resources you get access to. And how much is the enthusiasm you have about learning new skills. But technological knowledge... I have seen so many technical writers coming from so many different backgrounds, that sometimes I find it amazing that my team of technical writers that I work with that are full of variety of careers, that one can get inspiration from.

Lenora: Yeah, exactly. I know you talked about more the API pieces of documentation, and I feel that's such a nuance, because I guess I never thought about it in that way. I just thought, "Oh, okay. You just write and you post it online." I didn't know there was a process. So, could you go more into depth on that API process?

Sejal: So for any API documentation, there can be different ways of approaching it. You can either find out what an API does from your development team, and document it manually by putting all the pieces together, which is, as you know, it's done in many places. You can also find out if the team is using on specifications approach. So, there are two approaches of working with an API. One is a spec first, where the teams usually design the API inside specifications, and then take that to development. But then there's also called first approach, which is the case mostly in a lot of old APIs, where the APIs are already coded, but then teams transmit specifications out of it, to document them. They are commonly two types of API specs in the market are OpenAPI and RAML. RAML is created by MuleSoft, and now it is open source spec.

Sejal: But teams can create those specs, and then writers typically take those specs and generate documentation automatically by the tooling available to them. They add documentation inside the specs, the pieces of documentation are living inside the spec. So, they can even look outside the spec, and somehow they get connected in the end HTML product documentation. So, that is a key piece of automation that my team is working on, enabling writers with enough tooling and automation, so that they don't have to worry about manual ways of documenting APIs or any other developer artifacts--for example, SDKs.

Lenora: Yeah.

Sejal: Yeah. So they don't have to do that manually. And it saves a lot of time for writers as well. So, we are focusing on that automation part. But at the same time, there are so many parts of technical writing tasks that writers do from the beginning of finding out what are the changes in an API? What do I need to focus on documentation? How do I document, what are the formats of documentation that I write in? How is my documentation tested? Not just syntax, but are there any links that are broken? How do I publish documentation, is there an automated CI/CD pipeline that I have access to. So, all of these different parts, including delivery workflow for getting reviews from their teams, developers and product managers and editors, and accessing the content, finding out how good their content is based on Salesforce's award-winning style guide and writing tone.

Lenora: Yeah.

Sejal: So, a lot of these different areas need some sort of automation, and that is also something I'm focused on.

Lenora: And does it have some kind of feedback loop? Does the developers let you know, "Hey, this was helpful." Or do you have that little smiley face rating? Like, "This was great." Or, "No, that's not good." Do you have anything like that?

Sejal: We have that in our developer doc portal today. We have a feedback mechanism where developers can go and give feedback, and that is communicated to our writers. So, if you guys are giving feedback on Salesforce dev docs, be sure that our writers will know about that.

Lenora: So, let's get into more about how did you find your resources to learn? Because I want to get to a place where I'm trying to help out all those people that's trying to get into technical writing, may not know how, and just want to know where are some of the resources? How could they learn?

Sejal: One of the resources that I got was there were local training. So, I live in Hyderabad. So there were local trainings available in India, not in the same city, but remotely. And I took up those. However, I did not find that really useful. What I found useful was going through the content on different community places, like The Society of Technical Writing is one place that where people can look into. They have conferences all over the world in different cities happening and different countries. And those conferences are very helpful. I also found the YouTube videos very helpful. More than that, I found doing things on my own was more helpful. So, there is a wonderful community, which is of technical writers, which is called Write The Docs. Write The Docs is a ground up community of writers. And they have a really vibrant to discuss different technical writing issues or methods.

Sejal: I do follow them a lot, and understand what is happening in different companies, or what do different technical writers do? How to get started in freelancing? Because it's full of freelance tech writers. So if anybody wants to get started in freelancing, that's the place I would suggest because there are a lot of freelance technical writers out there. And you can get pointers from there. So, that is one big place. I learned a lot of things. And then I also started learning by doing so some of the tooling. I started using that to develop my own blog. This is some of the side projects like that, to understand how would I do it.

Lenora: That's a good point. I like that you even tried it on your own to say, "Hey, let me see how it works on my end." So it's easier for me to push this up for a company or whoever that needs this writing skill. So, let's start to wrap up. I wanted to ask you just one last question and that question was, what's next for you? What are you looking forward to?

Sejal: I look forward to developing myself more in product management. I've been doing that for a year now. I finally find that after changing five careers, this is the one I've landed on that will stick more, because I'm really enjoying it. I am loving the work that I'm doing, and it is making me look forward to every day of work. So, I look forward to developing myself more than into this.

Lenora: Awesome. Well, thank you so much for being a part of our show, and have a great day then.

Sejal: Thank you for having me. It was wonderful chatting with you.