Catch up on stories from the past week (and beyond) at the Slashdot story archive

 


Forgot your password?
Close
typodupeerror
×
Programming IT Technology

Desperately Seeking Documentation? 67

Posted by Cliff from the equally-good-with-pen-as-with-a-keyboard dept.
Interrobang asks: "I'm a longtime Slashdot reader, who isn't a programmer. I'm one of programmers' symbiotic (parasitic?) life-forms -- a freelance technical writer. I'd like to know from the programmers, IT managers, and similar others in the crowd: If you were searching the Internet for a technical writer, what kinds of search terms would you use? What sites would you check? Where and how would you start looking?"
This discussion has been archived. No new comments can be posted.

Desperately Seeking Documentation? More

Desperately Seeking Documentation?

Comments Filter:

  • How to get technical writing jobs... (Score:2, Funny)

    by Anonymous Coward
    1. Post a query to "Ask Slashdot"
    2. Wait for the jobs to roll in
    3. Profit!
  • I live in an area that's got plenty of technical writers looking for work. They have to go the old-fashioned route, look for a job like the rest of us.

  • If I were looking for a technical writer... (Score:4, Funny)

    by mwvdlee ( 775178 ) on Thursday January 19, 2006 @10:55AM (#14509145) Homepage
    ...I'd probably Google for "a life".

    But seriously, you want us to write your C.V. too?
  • Looking for a job ? ... Ask Slashdot!

    I believe that elsewhere the editor would be sacked for letting this rubbisch get through. Hm, we might have a recursive problem on our hands here if he in his turn would start looking for work on Slashdot.

    Arghl.

  • First mistake (Score:3, Informative)

    by Anonymous Coward on Thursday January 19, 2006 @10:57AM (#14509165)
    Using your precious /. link to optimize for an obscure punctuation mark [wikipedia.org] instead of "Technical writer". :)

  • craigslist (Score:1, Informative)

    by Anonymous Coward
    we recently hired a tech writer who answered our listing on craigslist. bigger companies would have an HR dept take care of this, but we're small and wanted somebody quickly/cheaply. turned out she was somewhat well-qualified so we took a chance on her, and it's worked out pretty well so far.

  • Why not post on... (Score:5, Insightful)

    by afabbro ( 33948 ) on Thursday January 19, 2006 @11:08AM (#14509267) Homepage
    ...rentacoder, elancer, etc.? Or if you want to hire perm, put your resume (and search) on Dice, Monster, etc.?

    Is there some rocket science I'm missing here, or is this just the usual lame Ask Slashdot from Cliff?

  • You need to network to find editors, not just toss out open calls via slashdot. There are several organizations for different writing specialities (computer tech writing, medical tech writing, business s/w documentation, game writing) as well as local writing groups. Think of it as joining the Guild for your special quest.

    For example, I mostly do science writing (with a little tech writing also). So being in the Nat. Assoc. of Science Writers (NASW) is helpful, but so is the local branch (DCSWA). Mostly

    • Re:Find a tech writing 'guild' (Score:1, Funny)

      by Anonymous Coward
      Hopefully you can find a guild that doesn't have unreasonable entry requirements [slashdot.org].
    • What I was looking for is answers like yours. The problem with just snarking off and saying I'm "looking for jobs on Slashdot" (I'm not; most of you are not my target market) is that well, most of you are not my target market. On the other hand, a lot of you will know things about places to look that I may not have thought of, which is why I think your comment is really useful and informative, despite what one might call "a slight tone problem." I'm going to be tracking down the science writing organizat
      • I heard your company featured in a podcast a while back -- some business/marketing one. I don't remember the name, but you probably know the one. If I were looking for a technical writer (and hey, as it turns out soon I just might be) I'd definitely give you some consideration.
         

  • I'd start off with "technical writer". This means I understand your role in the process. Therefore it is unlikely that I can help you now determine what a person would search for if they didn't know what they really wanted. Which is what you seem to be after. Sort of a "Dummies guide to making stuff people won't read about my cool project/product/website"

    However, as an engineer, lack of stupid has never prevented me from attempting to pretend to that blessed state, so:

    I'd search by using the ter

  • Seriously... (Score:3, Insightful)

    by aphoenix ( 877085 ) on Thursday January 19, 2006 @11:19AM (#14509381)

    Well, the first places to check are all the old standards: Workopolis, Monster, LinkedIn. I would also try Orkut now, but I'm a hardcore Google Fanboy (though the countdown to evil began a while ago). The search terms - well, that's easy. I'd try "technical writer" first and nothing second. If someone cannot make their resume found when I type "technical writer" then they aren't that technical and I'm not hiring them.

    The second place to check would be any local sites that may post classifieds-ish things.

    So here's my general answer to the questions? Where do I check? The place that resumes get posted.

    Of course, next time you have a question like this, I suggest that you jfgi [justfuckinggoogleit.com]...


  • If Google was up to it, I'd search /. for a story or posting that was free of errors in grammar, spelling, and punctuation.

    Hmm.

    Too bad I'm not in the market for a technical writer at the moment.

    But seriously, I suppose I would look for "technical writer," or "technical writing service" unless (as in fact, is likely) I had more specific requirements, e.g. "software documentation authors" or "product testing and documentation services."

    Which brings up a good point: I personally don't like to hire dedicat

    • If that's you experience with dedicated "documenters" you either haven't been hiring very good ones, or you haven't let them do their jobs properly. A good technical writer doesn't need a stint in tech support or testing in order to write a good manual.
      What they do need is cooperation from the engineers/coders/testers, and involvement in the project from an early stage (instead of the "oh, fuck, the project is finished and now we need a manual" management style).
      Also, in many cases you're better off hiring

      • I beg to differ.

        Would you expect someone to write a decent book about how to speak French without learning French? Would you expect a sportswriter to cover a sport but never watch a game, never talk to a player or a fan, but instead just get "cooperation" from the team's managers and staff? No matter how much "cooperation" the development team gives the documenters, no matter how much "technical background" they have, they need to use the product, even to the point of trying to break it, talk to real us

        • I'm not saying the writer doesn't need to use the product. Of course he does. But in my experience [1], the degree of involvement you want simply isn't necessary, nor is it feasible.
          1. Much of the documentation needs to be finished long before testing and/or product support come into play.
          2. There are usually many more testers and tech support people than writers. A writer's time is better used collecting information from that entire team, than taking over the job of one person in that team.
          3. The writer's

  • LDP (Score:3, Insightful)

    by jnik ( 1733 ) on Thursday January 19, 2006 @11:55AM (#14509741)
    Assuming I were attempting to pull a technical writer out of the vague Internettal æther instead of taking the more conventional route of putting up an ad for the job, I'd start by checking the Linux Documentation Project [tldp.org]. If a particularly well-written HOWTO (no jokes please) stuck out, I'd know how well the author could write without an editor, that zie could bring a project to completion, and that zie enjoyed writing at least to the point of producing something on a volunteer basis. Then I'd look at other online documentation, well-written technical books with short author lists, etc.

    I'd be looking for technical writing, in the flesh, not "technical writing" as a search term. You'll need some sort of portfolio or writing sample if you make it to an application anyhow.

  • I don't look for a technical writer, I look for technical writing. If you wanted to pimp your technical writing skills to me you should write some excellent documentation for various open source projects. Then just add a little note that you wrote the documentation and will write more for money. If you do this for the right projects, i.e: those which very desperately need good documentation, you might really make a hit. That's of course assuming you write very good stuff.

    Another good thing to do is write lo
  • what kinds of search terms would you use?

    symbiotic parasitic life-forms

  • Be proactive (Score:3, Insightful)

    by spyrochaete ( 707033 ) on Thursday January 19, 2006 @12:12PM (#14509938) Homepage Journal
    Make a web page. State your areas of specialty. Give a mission statement and post samples of your work. Explain how technical writers equal cost savings and work safety. Explain how hiring a professional technical writer can save money in client tech support by ensuring quality and palatability of the prose and layout. Give examples of places you've worked and how you improved their workflow. Ask former clients kindly for testimonials. Associate yourself with a guild like the STC [stc.org] or a local faction since this is often the first place prospective employers will look (or at least troll their job listings). It's a fact of life, however, that the people who need tech writers the most don't know that they need them. It sucks, but nothing beats cold calling business that reflect your specific areas of expertise. Throwing a few bucks to Google AdWords couldn't hurt either.

    Check out Managing Your Documentation Projects [amazon.com] by Joanne Hackos (or just read the first few pages [amazon.com]) for some great selling points to quote to potential clients.

  • Put up posters on college campuses (Score:3, Funny)

    by dheltzel ( 558802 ) on Thursday January 19, 2006 @12:56PM (#14510421)
    Since the CS students are outsourcing their coding to others, it's likely that lots of students will want to outsource their "documentation" as well. Can you do book reports and research papers as well?
  • I'd be searching for the TLAs relating to the technologies that I'd need writing on. If my product was a user-extensible CMS developed in PHP, my search would probably be for a tech writer with experience in CMS documentation, PHP and XHTML development, and CSS experience. Mostly, I'd expect that my techwriter was basically someone who had the skills to be on dev team, but who's talent is English prose, not code.
    • I think you're being way too specific. You want someone who can document your CMS, not someone who can write a book on 'how to program in PHP/XHTML/CSS'. For that sort of detail, you're better off referring the end user to an existing book on 'how to program in PHP/XHTML/CSS'.

      Some basic understanding of programming would be useful for this project, but you really don't need an experienced programmer to write the end-user documentation.
      What you do need is a writer who groks the concept of CMSs in general, an

  • Why hire a technical writer? (Score:3, Insightful)

    by Ark42 ( 522144 ) <slashdotNO@SPAMmorpheussoftware.net> on Thursday January 19, 2006 @01:22PM (#14510677) Homepage
    As a programmer, I admit that actually writing the documentation can be the most annoying and time-consuming part of creating a finished program, and I can procrastinate forever, adding tiny features to the program instead of spending my time writing boring English, but why should I hire a technical writer? When my progam is more-or-less done, I am the only person on the planet who knows how every single feature works, what all the hidden shortcut keys or shift/control+mouse click operations may do, and what the whole expected behaviour of any option is supposed to be.

    How could I possibly explain all of this to a technical writer to have documentation written, without just writing the documentation myself? Sure there are comments in the code, but they're not going to help write a idiot-friendly tutorial very much. Sure I have some planning scratch-pad-like text files or paintbrush image doodles of my ideas, but they might not fully represent all of the features, or even a particular feature in their final existing form anymore.

    I really loathe writing documentation, but unless the person helping my write it is involved in the entire program creating phase, sitting right there beside me the entire time, watching all of the features evolve, I don't think they'll be able to write complete help files.
    • I take it you've never worked on software developed by a team larger than 2-3 people?
    • Programmers write really shitty documentation (grammar is an issue, they don't understand the users, they make wrong assumptions about what should be documented and how) and are too expensive to let them do the job properly anyway. Like testing, writing end user documentation is best done by someone else. Let the programmer write code, designs and code comments.

      • Actually, I am pretty good with grammar, and spelling is easy enough to check. I do realize that at times I can document the wrong things, but that will lead to a volume of support questions all related to the same issue, which will make it into the FAQ and future documentation eventually. Even hiring a technical writer wouldn't eliminate that issue though, as users will always find some new thing to all agree to not understand.

    • ow could I possibly explain all of this to a technical writer to have documentation written, without just writing the documentation myself?,/i>

      This is a perfectly valid question. The answer is, sadly, that many technical writers serve in the capacity of editors. Especially in larger teams a tech writer is likely to find themselves gathering written documents from many individuals, and consolidating that content into a single, cohesive, work with consistent style and grammar. A good technical writer o

      • An important note here is that I am self-employed, and thus, a 1-man team. I do let close friends test my software, and they do help a lot with making the interface more intuitive, but only I really know all of the details of the unreleased program, and I don't think anybody else would be qualified for the first draft of any documentation at least.

        As for layout tools and print versions, I like to stick with just HTML. HTML allows me to have the help files all available online, and with some simple PHP tem

        • An important note here is that I am self-employed, and thus, a 1-man team.

          That does make a big difference. The normal ratio for a GUI development I've experienced is about one tech writer for 15 coders. You could hire someone to do contract work, but it may not be worth your time. Of course your program is very small with distribution only over the internet and only in one language. Should you ever grow to the point where you are selling boxed copies, you'll need print manuals. Also, more professional on


          • That is my point, I think - it doesn't seem to be worth my time to hire anybody to write documentation for me, even though I am selling boxed copies and only using HTML for help files.

            I didn't say that PDF files aren't printable, but that most users won't see any benefit to PDF over just HTML. Personally, the Acrobat reader is *very* slow and annoying to use, and the built-in search capability of Firefox or Internet Explorer works just as well, if not better, to search HTML. The main benefit to HTML thoug
            • the built-in search capability of Firefox or Internet Explorer works just as well, if not better, to search HTML.
              No, it doesn't. It finds text only in a single page. For any nontrivial application, you're better off separating the documentation into more pages, making the default search useless.
              HTML can be made to work, but you need an application like Webworks Publisher or AuthorIT to generate a fileset that also contains a table of contents, an index and a search engine.

            • Personally, the Acrobat reader is *very* slow and annoying to use

              This is true, especially when paired with the equally bloated IE. That is one of the reasons a lot of pros don't use either anymore and use a faster alternative.

              the built-in search capability of Firefox or Internet Explorer works just as well, if not better, to search HTML.

              This is just not so. First, browsers generally search one page only. Second, they generally find each instance of a search item in sequential order, one at a time.

    • Oddly enough, when I used to write programs (this was mostly back in my corporate days), I enjoyed writing documentation for them.

      Documenting your program (whether in the code or as part of the end user documentation) maximizes the odds that it will be used. Isn't that why you wrote it in the first place ?

      I know that the few end-user oriented bits I wrote (which rules out the X25 drivers) had ample documentation with lots of examples, and lots of "what-if" examples, which I actually enjoyed writing.

      But then
    • You'd be surprised. A writer, um, knows about writing stuff. He/she is (usually) much better than you at structuring information logically (i.e. from the point of view of the end user, rather than your 'developer' POV), and knows how to write so the audience can understand what's being said.
      Programmers who can do this are rare.
      A writer also really doesn't need to know how a feature has evolved. He just needs to understand the end result. Depending on the complexity of the subject matter, a writer can often
    • We use technical writers to create user manuals, on-screen help text, and other high level project documentation. The in-line code documentation is left to the coders.
  • Maybe it's just as important where you post as what you say...
  • Technical writers need not apply.

    If a company has some extra money to spend on head count, who are they going to hire? You, or another engineer?

    For the same reason most companies don't have a 2:1 ratio of testers to developers (more likely, 1:50 testers to developers), most companies don't have a technical writer.

    You might as well write a book about how to document your own code better. You'd probably make more money than you are now.

    • If a company has some extra money to spend on head count, who are they going to hire? You, or another engineer?

      If they are smart, they hire a tech writer, thus freeing the developers' time for dealing with coding rather than fiddling with LaTeX or MS Word or whatever documentation tools are being used and with the nicities of grammar. If you've got a twenty developers and each save 5% of their time by having a tech writer, you've just created another developer's worth of productivity at a tech writer's

      • But we all know that companies aren't intelligent about who they hire. If they were smart, they would hire 5 $15/hour testers instead of a developer. If they were smart, I'd have a personal secretary to help me keep on my meeting schedules, and even attend to take notes in my absence, and read my email for me.
  • If I needed a technical writer, the first place I'd check would be the dumpsters...then move to some seedy bars. But seriously, I'd probably google it.

  • If you were searching the Internet for a technical writer, what kinds of search terms would you use? What sites would you check? Where and how would you start looking?

    I've hired or been involved in hiring a number of technical writers. The first step to finding one, as with most other employees, is to ask within the company for referrals. The majority of coders and writers hired are someone recommended. Failing that, I generally post an ad and look through some of the common job sites or ask contacts a

  • I believe the intent of the question is that he wants to place the terms that people look for into his own web page or job listing so that he may easily be found. After all, if you're going to market yourself, wouldn't you want to know how people would look for you if they had to?

    While I don't have any tips on what search words to use, I do know what I would look for in a technical writer.

    1. Must be smart. I don't care how good you are at MS word, if you can't take a screenshot you're not getting hired.
  • From the logs on my website (I'm a freelance tech writer), it seems people aren't searching for technical writer or tech writer... they're searching for the actor with the same name as mine, the musician with the same name as mine or names/terms that happen to be on my quotes page. Other than that, clicks to my website tend to come from clickthroughs from my email sig when I post on a mailing list or from referrals from a couple sites I post my credentials on. All things considered, the website seems to hav
  • Personally, if I were you, I would consider which field you wanted to be in. If you are limiting yourself just to the IT field, then start looking at major companies with the money to hire permanent Tech Writers. Smaller companies that only need them occasionally will probably hire them on a contractual basis.

    You may wish to consider other fields with large companies. Or just be a contractor. Or find another career choice.

Slashdot Top Deals

"What man has done, man can aspire to do." -- Jerry Pournelle, about space flight

Close