4 ms·

A lot of technical writers focus on the style of the text. For example, I've seen tech writers have long discussions (more than 3 hour-long meetings) about titl

• voidhorse 7y ago
  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.
• theterriblestid 7y ago
  Even a computer without installed dependencies should be able to follow the docs. Some don’t list what dependencies they need at the beginning, which could save a lot of time and error messages.
• yardshop 7y ago
  I don't see where he says anything about style. Could you point out to me what he says that makes you think that? He does say to use bullet lists, but I think this is more about structuring the content and breaking ideas into steps than it is about style or formatting. His points all seem to focus on providing clarity and useful content to the reader and user.
  • BossingAround 7y ago
    > Could you point out to me what he says that makes you think that? I'd consider all of the following to be mostly style choices: * Avoid Meta Writing * Minimalist Instruction * The "Constructivism" section, e.g.--Engage in an active dialog, invite users to act “Please try”, “See what happens”, “Explore yourself” (The above is now what I'd estimate to be like 80% of the article) The reason why I'd consider that a style is that if you buy a style guide, e.g. the IBM style guide, it would include similar instructions, e.g. "avoid passive voice" or "be more succinct" (though at a more of an implementation level). It's possible you'd have a better name for it than 'style'. I'd accept that. My original point stands though; most TWs I've seen concern themselves with the letters of the documentation, and omit what I'd consider the most useful about documentation, that is the deep technical details such as maintaining code samples, or writing test suite for the documentation.
    • kaycebasques 7y ago
      First, let me get on the same page about your parent comment: > A lot of technical writers focus on the style of the text. For example, I've seen tech writers have long discussions (more than 3 hour-long meetings) about title capitalization in our organization. In general I agree that there are some technical writers who focus way too much on style. I also think that the list of practices that you described --- usability editing your docs, using a CI system and importing sections of the code samples into the docs to ensure that they're always working, being politically forceful about making sure that docs are treated as part of the core product and not an afterthought --- are all great practices. I agree that the practices you described should be established first before any debates about style. Moving on, I emphatically disagree that minimalist and constructivist instruction are "style" considerations. Style considerations are arbitrary decisions that you consistently follow in order to convey a sense of professionalism. In your first comment you provided a perfect example of a style consideration: title capitalization (e.g. whether to format your title like this "How to debug your code" or like this "How To Debug Your Code"). If we A/B tested a document to see if there was any change in user success rate based on title capitalization, there would be no difference. Minimalist and constructivist instruction are guidelines on how to create effective instruction. For example, the minimalist guideline to explain how to recover from errors is a hugely valuable practice which is extremely obvious once you are exposed to the idea, but is somehow a practice that many forget to do. To put it another way, if we A/B test a documentation set that follows minimalist or constructivist guidelines with a documentation set written by someone who doesn't understand those principles, I will wager money that the minimalist/constructivist doc set will lead to higher user success rates, however we agree to objectively measure that. Avoiding passive voice is another example of something that may seem like a style consideration but actually goes a long way towards making your communication much more effective. The problem with the passive voice is that it often makes the subject of an action ambiguous. For example if you write "the script is updated" it's not clear who updates the script. If it's something that the user needs to do, it's much better to say "you need to update the script". If the user reads the passive phrasing "the script is updated" and they don't understand that they need to take an action, that's the potential difference between user success and failure. As a meta note I'd really appreciate if you didn't say "most technical writers focus too much on style" and instead would say something like "the technical writers I've worked with focus too much on style". This is the equivalent of saying "most software engineers are code monkeys with no social skills" and it's really damaging to the credibility of my industry. But I do agree that there are some who focus too much on that BS and you have my word that I'm trying to rid my industry of that bad habit.
• habosa 7y ago
  Totally agree with your points about code correctness. That's the most important thing. I spent probably a year making systems/tools/processes to ensure that every code snippet in our documentation is imported unmodified from a GitHub repo with CI attached and that people reading the docs can see that. It's been a huge win.
• amelius 7y ago
  Also, document the data model more than how the code works. Famous Linus Torvalds quote: "Bad programmers worry about the code. Good programmers worry about data structures and their relationships."