Desperately Seeking Documentation? 67
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?"
How to get technical writing jobs... (Score:2, Funny)
2. Wait for the jobs to roll in
3. Profit!
Interrobang's Technical Writing Business (Score:1)
(Disclaimer: We go back a-ways in the Slashdot journalling community.^-^)
Re:Interrobang's Technical Writing Business (Score:2)
on a Windows XP platform. Sometime before the end of 2005, we anticipate being able to expand our services to include Mandrake Linux and Mac OS9.
OS 9! In 2005! Cutting edge!
Re:Interrobang's Technical Writing Business (Score:2)
Yes, technical writing is the steno pool of the 21st Century.
Dunno where you're located (Score:2)
If I were looking for a technical writer... (Score:4, Funny)
But seriously, you want us to write your C.V. too?
Re:If I were looking for a technical writer... (Score:1)
Re:If I were looking for a technical writer... (Score:2)
I think I've seen "CV" used all over the place. Although i seem to recall seing a couple from sowhere in eastern Europe with another title. Can't remember what it was now...
In case some US people are wondering, CV stands for Curriculum Vitaæ, roughly, the "flow of life", or maybe the "course of life". (and yes, the ae -æ- ligature is important). It's exactly the same thing as your "resume". Except it's better of course, because it's european.
(that was a win
Re:If I were looking for a technical writer... (Score:1)
Is it? I myself doesn't look twice on such a beast. The ligature, I would say, is a sure sign the writer doesn't know some basic Latin, or as in your case, is a frenchman ;-). Now, my field of research (linguistics) might have differing needs than other fields, but the only thing worse than the æ-ligature is people who don't know what CV stands for in the first place.
Re:If I were looking for a technical writer... (Score:2)
Sadly, English speakers seem to have dropped everything that isn't straight 7 bit ASCII. So the US gets "resume" instead of résumé and the UK gets curriculum vitae.
Thz hw U nd up wth SMS tlk IMO
Slashdot Recruitement Site (Score:1)
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)
Re:First mistake (Score:5, Funny)
Re:First mistake (Score:2)
Or, to clarify, it has as much existence as cattle mutilations, UFO abductions, intelligent design or astrology. Which is to say that while it has a marginal mindshare, typographists never used it, and aparently never will.
So while it's nowadays easy to create silly looking stuff (such as corporate letters in Comic Sans) it doesn't mean that those are part of any established typographical standard.
You might want to read "Eat, shoots, and leaves [amazon.com]" (plain Ama
Re:First mistake (Score:2)
Re:First mistake (Score:2)
Grow up.
Re:First mistake (Score:1)
Re:First mistake (Score:2)
craigslist (Score:1, Informative)
Why not post on... (Score:5, Insightful)
Is there some rocket science I'm missing here, or is this just the usual lame Ask Slashdot from Cliff?
Find a tech writing 'guild' (Score:2)
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)
It isn't an open call... (Score:2)
Re:It isn't an open call... (Score:2)
The words that describe the output of your work. (Score:2)
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)
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 (Score:2)
If Google was up to it, I'd search
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
Re:If Google was up to it (Score:2)
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
Re:If Google was up to it (Score:2)
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
Re:If Google was up to it (Score:2)
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)
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 (Score:2)
Another good thing to do is write lo
Search Terms (Score:2)
symbiotic parasitic life-forms
Be proactive (Score:3, Insightful)
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.
Re:Be proactive (Score:2)
Grab.
Put up posters on college campuses (Score:3, Funny)
Relevant Technologies (Score:2)
Re:Relevant Technologies (Score:2)
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)
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.
Re:Why hire a technical writer? (Score:2)
Re:Why hire a technical writer? (Score:2)
Yes, and those larger teams don't need to hire free-lance technical writers.
I am now a 1-man team though, which is what my previous post is really about.
Re:Why hire a technical writer? (Score:2)
Re:Why hire a technical writer? (Score:2)
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.
Re:Why hire a technical writer? (Score:2)
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
Re:Why hire a technical writer? (Score:2)
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
Re:Why hire a technical writer? (Score:2)
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
Re:Why hire a technical writer? (Score:2)
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
Re:Why hire a technical writer? (Score:2)
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.
Re:Why hire a technical writer? (Score:2)
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.
Re:Why hire a technical writer? (Score:2)
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
Re:Why hire a technical writer? (Score:2)
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
Re:Why hire a technical writer? (Score:1)
Monster or Dice? (Score:2)
We don't want your services (Score:1)
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.
Re:We don't want your services (Score:1)
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 they aren't... (Score:1)
Site? (Score:1)
Been There, Done That (Score:2)
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
Tips for Technical Writers (Score:1)
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.
Desperately Seeking Documentation? (Score:1)
Considerations... (Score:1)
You may wish to consider other fields with large companies. Or just be a contractor. Or find another career choice.
How to find documentation on hiring editors: (Score:1)