5 ms·

A fair observation. I do think there's some value to concerns over style, but far too many tech writers give them undue prominence. I couldn't champion your bu

A fair observation. I do think there's some value to concerns over style, but far too many tech writers give them undue prominence. I couldn't champion your bulleted points harder. Honestly, if I had a say in it, any tech writer working on developer documentation should be able to code/build/perform/use whatever task or api they're documenting without the help of an engineer. They should be able to read and understand code, and they should be willing to do so, even more so than the average engineer using some library code. They should be capable of understanding a library deeply and synthesizing and summarizing that understanding for users of the library. Just as tech writers in the medical field need to know quite a bit about medicine, tech writers in software should be required to know quite a bit about engineering software. There's plenty that do, but there's also quite a few that don't--I think it's a side effect of the field's relative youth. I really wish more writers would code and do exactly the things you mention, such as implement robust code sample testing, etc. The ideal technical writer, at least for software engineering documentation, is a hybrid of a traditional technical writer and a software engineer[^1]. [^1]: This excludes user-facing software documentation, which is essentially a totally different field than those that deal with writing for developer or engineer audiences.

geofft 7y ago
How does one become a technical writer? I'm a software engineer, and e.g. I recently applied to Google for both a tech writer position and a software engineer position, and they interviewed me and offered me a job for the software engineer role but they gave me a form rejection for the tech writer role. I worry I'm stuck as a software engineer because that's what's on my resume.
- gradschool 7y ago
  Writing something substantial and posting it online would help your chances. I was offered a job as a technical writer partly on that basis. I agree with the other comment that software development is preferable for the money, but on the other hand it's easier to switch off from technical writing at the end of the day or do your own projects after work than it would be if you were programming all day. While I'm at it, being a technical writer convinced me that software engineering and technical writing shouldn't be separate roles, because a lot of my time spent asking for clarification about things led to software engineers realizing they shouldn't have done it that way in the first place, and then changing it. If they had to write about it themselves, the feedback loop would have been tighter. Making them separate roles and paying technical writers less money probably started as some business guy's idea of division of labor.
biggestlou 7y ago
The problem with your perspective is an economic one. If you have the chops to be a hybrid TW/SWE, you will never take a tech writing job (or get out of tech writing as soon as you can) because tech writers simply make substantially less than engineers. Everyone acknowledges that tech writing is vital but until the pay story reflects that the status quo will persist.
Stratoscope 7y ago
> ...any tech writer working on developer documentation should be able to code/build/perform/use whatever task or api they're documenting without the help of an engineer. They should be able to read and understand code, and they should be willing to do so, even more so than the average engineer using some library code. They should be capable of understanding a library deeply and synthesizing and summarizing that understanding for users of the library. This is what made my friend Caroline Rose such a great technical writer. She not only can explain things in clear and simple terms, but she was also an accomplished programmer before branching into technical writing. Here is a story about the documentation that became Inside Macintosh: > I sat down to meet with Caroline for the first time, and she couldn't have been more different than the previous writer. As soon as I began to explain the first routine, she started bombarding me with questions. She didn't mind admitting it when she didn't understand something, and she wouldn't stop badgering me until she comprehended every nuance. She began to ask me questions that I didn't know the answers to, like what happened when certain parameters were invalid. I had to keep the source code open on the screen of my Lisa when I met with her, so I could figure out the answers to her questions while she was there. > Pretty soon, I figured out that if Caroline had trouble understanding something, it probably meant that the design was flawed. On a number of occasions, I told her to come back tomorrow after she asked a penetrating question, and revised the API to fix the flaw that she had pointed out. I began to imagine her questions when I was coding something new, which made me work harder to get things clearer before I went over them with her. https://www.folklore.org/StoryView.py?story=Inside_Macintosh.txt https://www.folklore.org/StoryView.py?story=Inside_Macintosh... One of my favorite examples from _Inside Macintosh_ is the discussion about the mathematical foundation of QuickDraw. Modern graphic programmers all know that a (0,0,0,0) rectangle is an empty rectangle. But why is that? Why isn't it a single pixel? The explanation on pages I-138 through I-141 is what made this concept make sense to me. Here's a PDF of _Inside Macintosh_: http://www.weihenstephan.org/~michaste/pagetable/mac/Inside_Macintosh.pdf http://www.weihenstephan.org/~michaste/pagetable/mac/Inside_... Besides that section, there are all kinds of examples of how to explain a complicated concept in simple and understandable terms. It's worth a quick skim of the entire book to see what good documentation looks like.
kaiby 7y ago
The issue with that though is that if someone could read/write code, they would probably choose to be a SWE instead of a tech writer. I'm not sure why this is, but I suspect that it's an combination of higher pay and an interest in writing code over writing documentation. In my experience I would say that a good SWE will attempt to write good documentation, as having to answer questions in the future about how stuff works over and over takes more time than just documenting things properly the first time.

geofft 7y ago

How does one become a technical writer? I'm a software engineer, and e.g. I recently applied to Google for both a tech writer position and a software engineer position, and they interviewed me and offered me a job for the software engineer role but they gave me a form rejection for the tech writer role. I worry I'm stuck as a software engineer because that's what's on my resume.

gradschool 7y ago
Writing something substantial and posting it online would help your chances. I was offered a job as a technical writer partly on that basis. I agree with the other comment that software development is preferable for the money, but on the other hand it's easier to switch off from technical writing at the end of the day or do your own projects after work than it would be if you were programming all day. While I'm at it, being a technical writer convinced me that software engineering and technical writing shouldn't be separate roles, because a lot of my time spent asking for clarification about things led to software engineers realizing they shouldn't have done it that way in the first place, and then changing it. If they had to write about it themselves, the feedback loop would have been tighter. Making them separate roles and paying technical writers less money probably started as some business guy's idea of division of labor.

biggestlou 7y ago

The problem with your perspective is an economic one. If you have the chops to be a hybrid TW/SWE, you will never take a tech writing job (or get out of tech writing as soon as you can) because tech writers simply make substantially less than engineers. Everyone acknowledges that tech writing is vital but until the pay story reflects that the status quo will persist.

Stratoscope 7y ago

> ...any tech writer working on developer documentation should be able to code/build/perform/use whatever task or api they're documenting without the help of an engineer. They should be able to read and understand code, and they should be willing to do so, even more so than the average engineer using some library code. They should be capable of understanding a library deeply and synthesizing and summarizing that understanding for users of the library. This is what made my friend Caroline Rose such a great technical writer. She not only can explain things in clear and simple terms, but she was also an accomplished programmer before branching into technical writing. Here is a story about the documentation that became Inside Macintosh: > I sat down to meet with Caroline for the first time, and she couldn't have been more different than the previous writer. As soon as I began to explain the first routine, she started bombarding me with questions. She didn't mind admitting it when she didn't understand something, and she wouldn't stop badgering me until she comprehended every nuance. She began to ask me questions that I didn't know the answers to, like what happened when certain parameters were invalid. I had to keep the source code open on the screen of my Lisa when I met with her, so I could figure out the answers to her questions while she was there. > Pretty soon, I figured out that if Caroline had trouble understanding something, it probably meant that the design was flawed. On a number of occasions, I told her to come back tomorrow after she asked a penetrating question, and revised the API to fix the flaw that she had pointed out. I began to imagine her questions when I was coding something new, which made me work harder to get things clearer before I went over them with her. https://www.folklore.org/StoryView.py?story=Inside_Macintosh.txt https://www.folklore.org/StoryView.py?story=Inside_Macintosh... One of my favorite examples from _Inside Macintosh_ is the discussion about the mathematical foundation of QuickDraw. Modern graphic programmers all know that a (0,0,0,0) rectangle is an empty rectangle. But why is that? Why isn't it a single pixel? The explanation on pages I-138 through I-141 is what made this concept make sense to me. Here's a PDF of _Inside Macintosh_: http://www.weihenstephan.org/~michaste/pagetable/mac/Inside_Macintosh.pdf http://www.weihenstephan.org/~michaste/pagetable/mac/Inside_... Besides that section, there are all kinds of examples of how to explain a complicated concept in simple and understandable terms. It's worth a quick skim of the entire book to see what good documentation looks like.

kaiby 7y ago

The issue with that though is that if someone could read/write code, they would probably choose to be a SWE instead of a tech writer. I'm not sure why this is, but I suspect that it's an combination of higher pay and an interest in writing code over writing documentation. In my experience I would say that a good SWE will attempt to write good documentation, as having to answer questions in the future about how stuff works over and over takes more time than just documenting things properly the first time.