Zohra 0:08

Hello listeners. In season two, we get the scoop on how you can build your resume, interview for success, and ultimately advance in your career. This is Insight Techcom with Sahara Mutabana. Let's get started. Hello, listeners. Welcome to another episode of the Insight Techcom show. Today's guest is Robert Delwood. Hi Robert, how are you?

SPEAKER_02 0:33

Hey, glad to be here today.

Zohra 0:35

Yes, thank you for being on my show. It's an honor, and I'm really looking forward to this conversation with you today.

SPEAKER_02 0:41

Sure.

Zohra 0:42

So tell us uh about yourself.

SPEAKER_02 0:44

So my name is Robert Delwood. I call myself a programmer, a writer, and a programmer writer. I've done all three in my career. I'm a writer by education. I'm a journalist through college. I'm a programmer by vocation. I'm self-taught since um sixth or seventh grade. But my favorite title is that of programmer writer, where I get to combine the two and I write to programmers about programming. I was working as a um as a programmer in Houston years ago in the mid-90s. And a buddy of mine had just moved to um Washington State, was working at Microsoft at the time, and he calls me up and he tells me about a position that Microsoft is looking for. They need writers who can write about programming. And literally within three or four months of that phone call, I was up in at Microsoft doing that. And I never looked back. Now, my career has changed from time to time. I've either always been a programmer or a writer, and I've always been able to combine the two. But specifically at Microsoft and afterwards, I did that exclusively.

Zohra 1:55

That's fantastic. That you are self-taught as a programmer. And I like the title of programmer writer. Because in your LinkedIn profile, you also have worked at NASA, and I definitely want you to talk about that experience. Can you share what you did at NASA and the information that I found?

SPEAKER_02 2:14

Oh funny. So I have been lucky in my career. I have worked at some cool, cool places. I am most associated with having worked at NASA, Houston Johnson Space Center. I was there in at two separate times for a total of about 15 or 16 years. This last time I was a titled developer. I was a titled programmer with some background on that. But one of my jobs was I was sort of a floating programmer. I wrote small, NASA loves their big systems where you know 30 people work on it. I, with my Mac with my Microsoft background, I was a PC developer. So I floated around groups, groups writing small applications that helped them do their job. And in one case, I was working with the um International Space Station's Stowage team, the team that tracked every everything that went up and down. NASA is absolutely fanatic of about tracking everything, and rightly so. It's important to them. And so I was writing an application that that was doing checks on that, and I did a spot check once. I just stopped the program to see if it was working right, and it landed on underwear. And you never really think about the mundane aspects. I had not thought about the mundane aspects of space. Certainly, if you watch all the TV shows about space, they have the hyperbolic drives and neural networks and such, but no one talks about laundry or water or just the very boring tasks. So yeah, I have got a doubt that the astronauts were entitled to a certain amount of private or personal, I should say, items, including underwear. They can choose their underwear and what goes up and to some degree what they want to wear. That was interesting to get that insight. And after that moment, I became just intensely aware of just how boring or literally down to earth a lot of space is.

Zohra 4:09

Oh wow. That is fascinating. I mean, it may seem mundane, but it's also pretty essential, I would say.

SPEAKER_02 4:16

Well, laundry, for instance, and I don't speak for NASA in this regard, of course, but laundry and on long-term space missions is not a pretty thing. They wear the same clothes for weeks on end. And I have heard of heard how astronauts can complain about the smell from time to time.

Zohra 4:33

Wow, who would have known? I never thought about this. So I learned something new. Thank you, Robert. That's awesome.

SPEAKER_01 4:39

Sure, sure.

Zohra 4:40

You know, you call yourself as a programmer writer and you self-taught programming. What kind of programming did you self-teach?

SPEAKER_02 4:48

So when I learned programming, we didn't have a lot of personal computers. I had to go to the local university. Now, fortunately, my brother was in college that time, so I could take along with him to use his computers. But there was a university right across from our street in where I lived in NASA that was actually pretty open to junior high and high school kids coming in and using their resources. So we'd go in, uh some some of my friends, friends would go in and use these big mainframe computers, but they did their job too. When PCs first started coming on the scene, I know this dates me a little bit, that was a huge, a huge advantage because I can now do it from my friend's house, not the university. And then I eventually got a um a uh computer. That was a big moment in my life. That's that's really cool. So the languages you had back then were sort of limited. I learned forms of basic. Each company had a slightly different flavor. The two big languages at the time on mainframes were Fortran and COBOL. A lot of those languages have essentially disappeared since then. But it founded an interesting idea in me that's lasted the rest of my career. And I'll go more into detail in a little bit. But basically, specifically when it comes to API documentation writing, there's a lot of talk about which language to learn, you know, Java or Python. And my feeling is, and this is what I advocate to anyone who'll ask me, it doesn't matter. Learn any language. 80%, 90% of every language is in common with the other ones. So if you learn basic and you learn the concept of looping, iteration going around in a through code, you know the concept. My other idea that I'm trying to advocate for people entering this community is to learn the theory of something, then everything else becomes an implementation detail that you can Google. So if you know looping is supported, and it's supported in most languages, and if you know basic, if you were to go over to C, you don't have to ask, for instance, does C support looping? You know the theory, it does support looping. You just have to Google to find that language's particular syntax. Uh, same thing if you uh you can switch over to Java, which is very much like C anyway, and you can Google looping search, looping. So it doesn't matter what language you learn, learn any language. And it doesn't even have to be a language, it can be a um scripting, a script, which I may also touch on in a moment. But learn that, and then everything else is just a variation of that. That alone, if you embrace those concepts, that alone would make any transition from tech writing to API documentation writing a lot easier.

Zohra 7:48

Okay. So, Robert, you know, I definitely want us to sort of flesh out the details. You've said a lot in that. Yes. And the reason I ask again is I understand programming conceptually. And I've learned how to program in Java, I've learned how to program in C, but I think unlike you, programming doesn't come naturally to me. And I'll tell you why. As I said, conceptually, I can I know that you can do looping in Java and C and C. But you see, I'm just not a good programmer. So my question is I agree with you that understanding conceptually, at least it's you're informed, you understand what looping means. I think you need to start somewhere. So you definitely need to understand the concept. But as a programmer writer, how deep do you have to go for somebody like me who is not comfortable with programming but still wants to segue into API documentation?

SPEAKER_02 8:44

So there are a couple of aspects to that question, and it's a common question. The first thing you you someone has to look at is is this field right for me? I love this field. I love programming writing. It was, I think it was what I was meant to do. And I advocate it, and I want everyone, and we really need this industry, this community needs writers right now. We're far exceeding our document. The industry is far exceeding the capability. But there is a bottom line in that it may not be for everyone. I can't help answer that for everyone. It may not be even be a question that you know up front. Maybe it's something that you'd like to do, and once you're in it, it's not right for you. And that's perfectly fine. But but there are a couple things that you can do to test it or to get into it. First of all, it is a programmatic world. You're entering the title's called programmer writer, you're writing to programmers and you're teaching them how to use your company's tool programmatically to make their product. So absolutely, there is that aspect. And at some point, you're going to have to embrace, embrace programming. If it's something you're good at and like, it's a craft. It's a skill and it's a craft that it has to be developed. If you find out it's not right for you, then by all means, don't do it. It'll just be a disaster for you and the company. But along the way, a couple things I've noticed throughout my career. Most of the programmer writers I know, like I said, this is a very misunderstood community. Not everyone knows about programming writing. I have several articles I've published where I vilify CEOs for not understanding programming writing. And again, I'll get to that in a in a moment. But most of the programmer writers I know got in by accident. However, you look at it, they were in the right spot at the right time or the wrong spot at the wrong time. But they were technical writers and their bosses asked them to move over to programming writing. That's what the company needed. And many do well, many flourish in that environment. So after hearing that several times and watching firsthand these tech writers turn to API writers, there is a success path. Once you get into it, once you understand it is a craft and people are depending on you and you accept it as a craft that needs developing, people do well even without knowing programming going in. Because you will learn on the job. You won't be asked to do the most complicated thing at first. You'll be asked to do a very simple thing. And the very simple thing becomes a less simple thing. And along this spectrum, you will go. In terms of your success, so it is a spectrum. Imagine a spectrum that on the left end you have zero programming, zero knowledge, and at the right-hand extreme, you are an expert programmer. The more you are on to the right, the better you'll be in this role. So if you move a little bit to the right, you'll be a little bit good. If you move a lot to the right, you'll be a lot good. I will never give the impression that once that's binary, that once you're a titled API writer, you will know everything about the profession. You won't. You will be limited only by how much programming you know, which is a very large spectrum. But the point is, once you get in, then you start learning your trade. So in your case, and correct me if I misunderstood any of this, you know the little programming, but you know the concepts loop, loops, decision making, variable assignments. And that really is enough to get you started. You won't be asked to write code samples because you probably couldn't write code samples, not certainly not to the degree that seasoned programmers would want to see. You would be expected to describe API calls and API parameters. Those are actually very easy to do. You get a um call get next event. That's an old Apple one. But even from the name, you can sort of surmise there's an event queue. And so you write a sentence or or two about that. So whenever writing documentation, for instance, I always advocate doing it as a series of passes. The first pass is that every method and every parameter have a one-sentence description, and that's it. This call does X, this parameter does X. And that does that does a cut a couple things. One of my philosophies is you document it for yourself. You're documenting APIs for yourself. If you don't understand something, that is worthy to stop what you're doing and learn it. Chances are others won't understand it either. So this is actually a self-teaching job in that regard. If you come to a parameter or concept you don't understand, you stop, you learn it, you explain it, you move on. Over time, you're going to learn the API concepts that are involved. Now, beyond that, the second, third, and maybe even fourth classes go start going increasingly into detail. But if you take short, small steps, just one description, a lot of the APIs don't even have that. And that's the problem. So a company starts out, they think they want an API, they develop it, but they literally have nothing. I've seen in the in the last four months alone, I've seen API suites that have zero documentation. So there is a lot of value if for someone to go in and be able to add these descriptions. That would be your first entry point in it. Notice you're not doing doing any programming, but you will be you will be confronted with programming. You may have to look at code. You may not be an expert programmer, you may not sit down and be able to sit down and write programs, but reading code is actually very, very easy. Let me rephrase that. Reading code is easier. You can get the gist of what the code does, even if you don't know the language itself. So for that, for someone like you, if you were to ask me this question again, I would say not knowing a language isn't a roadblock to entering the profession. Again, I said this a minute ago, once you're in, you're on a skills and crafts track that you're expected to learn. But then again, so is anything. Tech writers, once they get their topic, are expected to become experts in that topic. And it's not a quick journey. It doesn't necessarily have to be a quick journey. I've often said a good wine is never developed overnight. It can take years. But if you're starting out, don't let that be a roadblock to you. Now, you know some programming, even if someone didn't know any programming, that's not necessarily a roadblock either, because it's something that's learnable.

Zohra 15:46

I was trying to take notes and then I stopped because I wanted to pay attention to what you're sharing with me.

SPEAKER_01 15:51

Yes.

Zohra 15:51

Right? I think some of the things that I took away was the spectrum that you know you can you can start small. And then I I think what gave me more confidence was even if you don't know programming, it should not be a roadblock to you. You can find your path and like you start tweaking. So the immediate question that I would like to ask is for somebody who, let's say, does not know any programming, are there APIs out there that they can write about? How do you get started on this journey?

SPEAKER_02 16:19

A couple ways I would recommend. One is to learn a language. These days there are so many ways to. I learned the most basic and old-fashioned way. I just got a book, put it in my lap, and did each example as and followed through the book. But there's online classes, Linda, there's videos. There is not a shortage. If you want to learn a language, any language, there's not a shortage out there for anything to learn. But that's something that you can do right now. Now, I also advocate that there's three things that you you can do. I just did a previous seminar called seven skills you can learn right now. Seven skills you would need as a API developer that you can learn right now to do your job. So even if you're thinking about switching over, if you're curious about, or even these are just good skills that any tech writer should know in my mind. So number one would be to learn a language. Again, and any language is good enough. Now, if you know you're going to be working for a company that does web development, then yeah, Java would be a logical choice. You don't want to have to learn two languages that wide. So, and if you're ASP, my main language is C sharp. Again, the language that doesn't really matter. But you don't even have to learn a language. A minute ago I said it can be scripting because the same concepts are there. So if you use Word, for instance, my one of my other specialties is as an office developer. I write at NASA, I also wrote work, I was privileged to work with two or three different writing groups specifically where I got to automate anything we wanted. That was a cool job. That was a cool aspect of the job. But if you know Word, for instance, it has a it has a very impressive built-in macro language. You can record scripts from your screen, it produces textual scripts that you can modify. Learning that is also very good towards API documentation. Anything that gets you in the mindset of a programmer is the skills that you need. So if you learn macros, if you write macros, if you record macros and you eventually end up modifying them through their text editor, you're on a good row. Plus, it has two other advantages. One, you get to do your job better. Writing these macros is probably some is probably a task that you want to automate right now. So you learn a language and get to do your job. And the reason I say that is learning a language by itself is pretty boring. Learning for learning sake always is. If you can apply that knowledge to what you do, it's going to make it more interesting. You're going to spend more time with it, and you're going to push yourself. My favorite part of any automation project is where the audience, the clients themselves come up to me and say, This is great, but can you do X? Now they're thinking of ideas that they want to do with my automation. And if we can combine their ideas with their own ability to do it, you're learning programming. The third aspect of this, and this is actually the most important in my mind. So if you learn a programming like, you sympathize with your audience. You sort of know what challenges they're up against, you know, the technical, you know, all the problems and the benefits, but in a very objective way. We don't want to sympathize with our clients. We want to empathize with them. We want to know what their pain points are, what makes them excel at their job. If you learn a language, push yourself, you will come across those pain points too. Be especially attentive, for instance, things that you don't get. If you read something several times and you don't get it, that's a problem. Now you're empathizing with the with your audit, your your audience because you're trying to communicate an idea that's not coming across. Conversely, if you read something, it is almost in a piphany-like reading paragraph. Study what just happened. Why is it easy to learn? Why was that con was it the example that made the concept come alive? Was the text so clear and so and written in such a vernacular so everyone understood it on first reading? Learn that. And that will make you empathize with the audience. Things that you don't like, either abandon in the future or try to improve. Things you do like, improve. Either way, whatever you're doing, you're improving. Because it um because if you get a book, let's back up a second here. If you get a book about a language, they have knowledge they want to convey to you. You have information that you want to get from them, and they are trying to put it in the clearest terms and the shortest path possible for you to learn it. By definition, that is API documentation. Pure and simple. Learning the language from a book is no less API documentation than anything that you would read from Google about the product. So by learning a language, by applying it and learning it yourself and pushing yourself to do more and to be more specific and to understand how you learn that language. Those are three essential skills that you can start learning now, and that'll apply to any API programming job. Believe me, once you get into an API writing, you will have a Enough to keep you busy otherwise. So learning stuff that you can learn now is actually a problem. Learn what you can now and free yourself up to learn what the company wants to teach you. Those are three very important aspects to learning code and starting off right now. Starting out, the one thing that I want to dismiss the most is that it's scary to get started. There are a lot of good websites about this. There's a lot of good information out there. But in my opinion, they all tend to be a little bit scary because they focus on the technical details and it becomes a technical hurdle that if you can't follow these eight steps in setting up a program, that this isn't right for you. That's not right at all. Don't be intimidated about even looking into this industry. And like I said before, if you come across a procedure that doesn't work for you, your responsibility to change it, so it does work for you. You're writing for yourself, and in turn, you're going to be writing for others too. This is one thing that's not very well publicized and is also part of my foundation in advocating what I'm advocating. This is not a science. There are no hard, hard requirements in this industry. A lot of times, when you look at starting with job descriptions, they will list five, eight, ten requirements into in order to accept this job as an API writer. You have to know language X, you have to know Git or some other some um tool. No, you don't have to know any of that. If you learn the expectations of what the cloud of the clients in communicating concepts from the API, it becomes an art now. What works for you? What is your style in learning? What is your style in teaching? If we get to come across a new idea in API writing, we all have one. And that's purely up to you. Don't think there is one right way of doing it, or if you don't do it, it's wrong. It's however you can communicate the information to the writer so they can use your product. That's the only expectation that should be met.

Zohra 24:18

Okay. I think my original question came back to me. How does one go around building a portfolio? And you answered, you covered more than I could have asked for.

SPEAKER_02 24:28

Sure.

Zohra 24:28

That's great. And also one of the things that I feel like as a writer, there is this common mindset. No matter whether you're a traditional writer or you want to break into this cool quote unquote field of uh API documentation, you know, you have to be first of all open to learning and then progressively learn. You got to start somewhere, but not to be intimidated. I think it is relatable. And I feel encouraged that okay, even if I don't know something, I can. And I think some what I liked, really liked about your advice was you don't need lots of resources. Even if you just have words and writing macros can put you on that path. I think that was my biggest takeaway, that it can be these small steps that can help you build towards your objective of becoming an API writer. And I think I'm personally going to apply that because I do that. I use Matcap Flare and I do write, I try to automate some of the things that I do. And then I like to look at the code of what that looks like. I've written a little bit of scripting in the past. So I think I already feel encouraged and motivated by that. Oh, good. By the fact that, okay, you know what? It's not that intimidating, as you said.

SPEAKER_02 25:38

To answer your question about how to build a portfolio, I'm going to answer it pretty broadly. If you can't tell, that's what I do. One of the problems with this community, and I said a minute ago, it's misunderstood. So, as far as I know, and if any reader or listener knows otherwise, please let me know. No college teaches API documentation writing. So you can't go to college and get a degree in this. It is far enough away from technical writing that, and while all knowledge is good, while all skills are useful, it's really not close enough to tech writing to get a degree in tech writing and then assume the next logical step is that. I don't even call this tech writing because there is such a heavy programmatic aspect to it. So you can't go to college. There are private companies that offer certification, and there, and those are great, but they're far and few between. So the only way you're going to really learn this is on your own. You'll have to spend the explicit effort to find something. So to answer your question, how do you build a portfolio? I would suggest one, writing your own API. Now, an API is not always REST, it's not always a DLL in PC terms, but write a series of methods in your language that does something. Math or accounting or science or something. Just you yourself write four or five of these, then explain it as if you explain what it is, how you would use it, why you would use it, and the terms, as if you're just going to hand that piece of paper to a friend and say, Would you test this for me? Does it work? That is the very start, that's the very essence of what API documentation writing is. You're explaining what code does, and it has to be clear enough so that someone else understands it. So write your own methods on your computer, uh, write it up and to a friend and have them look at it. What they don't understand, improve, what they do understand, figure out why they understand it, and do that exact same thing again. The second way of doing it is look at APIs, look at tons and tons of existing APIs. Fortunately, there is a website called the Programmable Web, which is an excellent resource. It lists the number increases every day, I think for up to 30,000 public APIs, and they range in professionality from a company's they list Google APIs, but down to the guy who I think has a Chuck Norris joke of the day API. In other words, pretty simple. Look at them, look at the API, read what the APIs say. There's gonna be some APIs you you like more than others. There's gonna be some that you find you will find after a little, a very short little while that you'll dislike some APIs. You may not have ever done this before, but you'll look at it and say, my goodness, that's a horrible job on on it. And I'm not criticizing the people, the that that's not necessarily their point, and they're doing an honest an honest job at writing APIs. But it but my point is in a very short time, you'll come to like some and dislike others. Beyond that, I have something that I call a the 30-minute limit test. And can you take take an API at random from the or selectively from the programmable web and try to implement it? Try to make a call, one call using their documentation. Can this be done in less than 30 minutes? If the answer is yes, really good ones should be five to 10 minutes. 30 is a it's just an arbitrary point. But if you can do it in less than 30 minutes, that's a good API. If not, you can figure out why you couldn't do it. What piece there's and there's usually just one or two assumptions. That's the problem with API writing, is that you can always get too close to your subject and they'll leave out one important information. They may say, you enter your access token number here, but they don't talk anything about where that comes from. Well, that's a problem because you can't make the call, but you've learned something. You can't make any assumptions. What's obvious to you will not be obvious to others. In fact, that's one of the things you you always have to look out for in this profession is that you've become too familiar with the project and you're making those same mistakes now. You assume they know what the object ID is and where it comes from and what it does. And you can't, you always have to watch out for that. A third good way of doing it is volunteering to help people. There are a lot of freelance sites like Upwork and offhand, I forget. There may be one freelance, is that right? That are almost always looking to some degree for writers for their APIs. Approach them. You have absolutely nothing to lose. I've never done this before. You don't even have to paint. Just let me do it and see if you if you like it. If you get paid, so much more better, but that's not the point. You're trying to build a portfolio right now. Those are actually three or four very easy ways to start building up something to show.

Zohra 30:53

You know, I always thought in my head I had a very complicated way of thinking and approaching this topic. And what you've done is simplified for me, that it's not insurmountable. Now, a few months ago, I was looking into, you know, how do I develop a new skill set? And API programming was something that I was looking at. And I came across I would rather be writing Jim Johnson's.

SPEAKER_02 31:15

He has it, he has the outstanding, yeah, he has the best in the business.

Zohra 31:19

Right, right. And I mean it's an outstanding tutorial, if I may say so. And I started off with it, and then I was fortunate to kind of get another opportunity, and I started off there, but I felt that was another resource that I was looking at. And then incidentally, a teammate of mine is looking into that tutorial. And like you said, I think what you're trying to say is there are a lot of avenues out there, and there are easy ways for you to get that experience and to build your portfolio. So that's good. You've just made it accessible for listeners like me.

SPEAKER_02 31:51

Well, well, good. And that's the point, too. Another problem with the industry or community is APIs are growing almost exponentially. Go to the programmable web, they have a now famous chart that shows the growth, the growth, and and the line is going almost straight up now. I think they say there's 2,000 new APIs a year. We're not recruiting 2,000 writers. And 2,000 isn't isn't enough. You know, each API needs two or three writers. So we're 6,000 API writers a year behind schedule. I started to say you can't go to college for it. You can get a um certificate, but um there's probably not enough enough of these of those organizations. And the third way of um the third organized way of training is to let the experienced writers teach the inexperienced writers. Unfortunately, there are not, and I'm gonna put myself hopefully modestly in that group. I've been doing it for a long time, and and I think I'm one of the older, the older people, but there's not enough of us now to train the new people. We're retiring. And as we go, these people have no one to train them. Even documentation writers are even documentation managers aren't necessarily trained or experienced in API writing. My um I've always said to treat an API writing project like a tech writing project gets tech writing results, and that's just a disaster for everyone. There are a lot of levels and there's a lot of details to API documentation writing. So, for instance, I've often said there's no end to API documentation writing. So you can always go in and add more data. Tech writing is a little bit different. I don't want to minimize or minimize any aspect of a tech writer, but usually their topics have a definite starting and ending point. Let's pick the most simple case possible, a login screen. There's only two or three items on that screen. And there's only two or three things that you can write about. Now it gets more complicated, of course, as as you go into the project, but the concept is still there. There's really only so much. So you can say in a tech writing project, you know, let's spend six weeks on this one topic and go completely to the bottom with that. And you can do it. So in six weeks, you know, you'll be you'll be done in that project. That concept does not exist in the API writing world. There is just always more detail. I said that I often do it in two or three passes. And I say that because you have to have a cut off cutoff point for each stage of the project. Otherwise, you can just spend literally weeks and months on one or or several calls just keep digging into it. So that's what I mean, and that's only part of it. But that's what I mean. If you treat it like a tech writing project, it's going to be a disaster because you're not going to get the detail you want. The audience isn't going to get the information you want. And no API writer will be satisfied with the work they've done. It's frustrating to them. So I do I do warn about writing managers who don't have API documentation experience either. So without the traditional ways of training people, school, vocational school, and experienced writers training you, the most common way is to just throw someone into a writing role and have them in a sink or swim position. A minute ago, I did say a lot of them were sort of forced into it and they learned as they go. That's pretty much a sink or swim. They don't have anyone to look to look forward to. There's very little documentation on what the expectations are. And you can do that on an individual basis, but to do that on you can't do that on a community or industry-wide wide basis. That the industry is saying, well, you know, we're going to get all the API writers we need from the pool of available tech writers, and we'll just promote them into this role. That is a very bad way of making plans. Unfortunately, that's what we have right now. So I'm I'm trying to get people think ahead of time things they can do to ease that transition and so so that they'll have an idea once they're in there what they're doing. I mean, I was trained in the sinker swim at Microsoft when I got hired, hired to board. Now remember, this was a brand new position, I think, for the industry. Definitely Microsoft. They didn't have um API writers before. The guy who hired me was only there for a week. We were only there in common for a week, then he left. Literally, I didn't know what to do first. I didn't know enough to hit even new in Word to create a page to start writing about it. But you eventually fumble around, you ask, and you can and you figure out what's needed, and you sort of evolve from there. But again, I can't advocate that as a industry-wide training.

Zohra 37:00

Overall, I think like any other industry, I think there is sort of this learning curve, and and we are trying to take some baby steps here with API documentation, probably. And I've definitely not worked in this field, so I'm going to lean on your experience with everything that you said. And I think if the sync or swim analogy sort of I have something to say about it, is in my personal experience at the previous job, I did volunteer to do API documentation, but they didn't have any framework. So I volunteered to just create a framework. What would an API documentation look like? And I would work with engineers. So I try to start off with that. And then again, like you said, your doc managers do not come with experience. So sometimes you may have to step up and take that initiative and work with them. And this is just a different perspective that I'm trying to bring to the table. You're absolutely right. When you try to fit API documentation into that mold of traditional technical writing, which I that's that was my primary objective, it was a challenge. And we could not fit that into a sprint. And how do you kind of come to a happy place? And there are going to be some teething problems, looks like.

SPEAKER_02 38:12

And for a new effort, yes, you will absolutely have friction at the beginning. The funny thing about this is everyone is going to claim they're an expert at what you do. Uh, from the documentation manager who's been in the role for you know 10 or 15 years, they know exactly how to do API docs. You're going to have the dev manager intervene because he likes he likes his documents this way. And then the devs, the individual devs, tend to have tunnel vision. They're looking only at one thing. They're absolutely right, but there's more, there's, and all these people are absolutely right. Let me make it more general. They're absolutely right in their statement. But your concern is that you have a much wider scope. So the developer manager, for instance, will almost always have an opinion about what they like in API documentation because they're experts and have been reading documentation for 20 years. Yes, he's right. Everything he says is applicable to his audience. But you're not writing only to his audience, you're writing to new people coming into your product. And that is a different kind of writing entirely. Now, you'll learn that on the job, but the point is, everyone is going to come up to you and say you're doing it wrong and it needs to be this way. And I believe in the API documentation-centric approach, where if I'm the lead on something, I am the lead and you're going to listen to me because I have the big picture on what API docs are. I'm not an expert in any other aspect of business. I'm not going to tell marketing writing how to do their job. I'm not going to tell the copywriter how to do her job. Devs, you know, I don't know their job. I can't be, and I'm not going to presume that. I know API documentation writing. In terms of being a strong lead, yes, there is that aspect. The stronger you can be from the start, I think ultimately it your job will be so much easier. But again, that's an individual trait. Some people aren't comfortable standing up and resisting everyone's contrary thoughts.

SPEAKER_01 40:19

Yes.

SPEAKER_02 40:19

That's part of learning. That's part of training.

Zohra 40:22

That's part of training too. Okay.

SPEAKER_02 40:24

Push back where you can learn to build consensus when you need to. Train team build. It's so much easier if everyone just cooperates with you. But that's like a pipe. That's all another topic. There is a silver lining in all this. My bottom line is I just like what I do. I love what I do. I love doing it. I love talking about it. I like every aspect of it. More tangible results is API documentation writing is usually on its own separate pay scale. It should be higher than tech writers because you're using more skills. You're sort of halfway in between a tech writer and a developer. And companies that recognize this, and I will call those good companies. If they recognize it, then your pay will reflect that halfway point. Now, I don't know every company's scale, so I can't give even percentages here, but I can say that API writers are typically above tech writers in pay and slightly below programmers in pay. That's the goal that you're going for. So when you do switch over and you talk about salary, just don't take your salary and just add 10% to it. Add start off by literally maybe 50%. You're going onto a new pay scale. You're not jumping within your existing one. I just introduced the concept that there are good companies and bad companies. Good companies will recognize that APIs are documentation is writing. For instance, the whole reason APIs need to be documented in the first place is because programmers can't discover those calls themselves. You would have no idea if you wanted to write an application that hit Amazon, you would have no idea what the calls are, the parameters are. And there's no place really outside of documentation that you can go to figure those out. So I say, so the companies are all used. They've had 60, 70 years of business industry experience about hiring expensive programmers to come up with these cool top-notch products. But unless you tell anyone about the product, what is the point? It's that great American novel that every writer has next to them on their desk. Could be the best thing in the world, but until it's published, it doesn't matter. So a good company will realize that, and my saying is the documentation is the product because they can't use it without it. Good company will recognize it and will make an effort to accommodate writers. Again, it may be a new experience for them too, if they never use it. They don't know what these people do, where they come from. They just know the concept is good. But they will work with you and they'll pay you well. I'm not all about money, but there is a dignity and satisfaction in getting paid for what you're worth. A bad company doesn't recognize that. They'll see you as chattel, and if you can do this kind of writing, you can do that kind of writing. And every writer knows that's not true. I can't write fiction for to um save my life, even though it's writing. Right. And even though I'm a native speaker of English, it doesn't mean I'm always a good writer either. And I hear that a lot. Why should I have to pay someone who's a native speaker more money? Well, because we're not just using the language, we're combining words and concepts to communicate technical and sometimes confusing topics. That's what you're paying me for. Not to use good and well, well correctly, although please don't mix those up. So that's the concept of good and bad. If you come across a bad company, consider your options.

Zohra 44:01

That's good advice. I think very sound advice. Uh Robert, we've been talking for a good hour. And we've had such a fantastic conversation. I could continue for another hour, but of course, is there anything that uh we've missed out that you would absolutely like to talk about?

SPEAKER_02 44:17

No, not really. I've talked about the important thing. The what number one thing, if I can stress to anyone, is you should not be intimidated by this community. There's nothing to be intimidated about. And yet, there are so many places that will try to intimidate you intentionally or unintentionally. And don't give in. Don't give in to that. Learn expectations, meet the expectations of the readers, and you are on solid ground. You can claim anything you want. If they're using your product, making what they need to make and not be asking a lot of questions along the way. That is the definition of success.

Zohra 44:58

And on that note, Robert, this has been an awesome insight for me. I want to personally thank you for sure. No, it's awesome to be on my show.

SPEAKER_02 45:09

My pleasure.

Zohra 45:11

Yes, thank you, and you know, have a wonderful day.

SPEAKER_02 45:14

Oh, thanks, you too.

Zohra 45:16

I hope you enjoyed this episode. Subscribe to the podcast on your favorite app, including Apple, Google, or Spotify. Follow me on LinkedIn or visit us at www.inside techcom.show for the latest updates. Catch you on another episode.