Beta

Slashdot: News for Nerds

×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Desperately Seeking Documentation?

Cliff posted more than 8 years ago | from the equally-good-with-pen-as-with-a-keyboard dept.

Programming 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?"

cancel ×

67 comments

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

Anonymous Coward | more than 8 years ago | (#14509055)

1. Post a query to "Ask Slashdot"
2. Wait for the jobs to roll in
3. Profit!

Interrobang's Technical Writing Business (1)

leoPetr (926753) | more than 8 years ago | (#14509849)

Since Interrobang neglected to link her site and thus reify your joke... behold the glory [sara-stewart.com] !:P

(Disclaimer: We go back a-ways in the Slashdot journalling community.^-^)

Re:Interrobang's Technical Writing Business (1)

antifoidulus (807088) | more than 8 years ago | (#14510502)

From the site:
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 (1)

Interrobang (245315) | more than 8 years ago | (#14510753)

Well, it's Perfessor Multigeek's computer; maybe you should take it up with him. You could say I'm more interested in being Reed and Wright [reedandwright.net] compatible than Mac-compatible at this point. When I start making programmer-type money instead of technical writer type money, maybe I can get a new Mac. *grin*

Yes, technical writing is the steno pool of the 21st Century.

Dunno where you're located (1)

faloi (738831) | more than 8 years ago | (#14509095)

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.

Dunno where you're located-SWATing the problem. (0)

Anonymous Coward | more than 8 years ago | (#14510746)

"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."

I don't think that kicking in doors, and dragging bosses out to an interview will work.

If I were looking for a technical writer... (3, Funny)

mwvdlee (775178) | more than 8 years ago | (#14509145)

...I'd probably Google for "a life".

But seriously, you want us to write your C.V. too?

Re:If I were looking for a technical writer... (0)

Anonymous Coward | more than 8 years ago | (#14509199)

One of the things that ensures I don't hire someone is when they get all pretentious about their resume and call it a CV.

Then again, I've been burned 100% of the time by academic types. Mostly, I need achievers.

Re:If I were looking for a technical writer... (1)

blacksway (464427) | more than 8 years ago | (#14510003)

We call them CVs over here in the UK, not Resumes.

Re:If I were looking for a technical writer... (0)

Anonymous Coward | more than 8 years ago | (#14512875)

And we have suprisingly few Brits working here as a result. hehe.

Re:If I were looking for a technical writer... (1)

Fred_A (10934) | more than 8 years ago | (#14513153)

I think you can s/UK/Europe/ actually.
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 wink, hence a joke, I am French, I surrender)

Re:If I were looking for a technical writer... (1)

asdfgl (891883) | more than 8 years ago | (#14525825)

and yes, the ae -æ- ligature is important

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... (1)

Fred_A (10934) | more than 8 years ago | (#14526206)

Actually the æ character is quite latin in origin and was used at the time. It was also used in old English and Merovingian.

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 (1)

christophe.vg (742168) | more than 8 years ago | (#14509154)

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 (3, Informative)

Anonymous Coward | more than 8 years ago | (#14509165)

Using your precious /. link to optimize for an obscure punctuation mark [wikipedia.org] instead of "Technical writer". :)

Re:First mistake (4, Funny)

antifoidulus (807088) | more than 8 years ago | (#14510637)

I thought an Interrobang was where you had sex while speaking in nothing but questions.

Re:First mistake (0)

Anonymous Coward | more than 8 years ago | (#14512574)

I thought an Interrobang was where you had sex while speaking in nothing but questions.

Isn't that what they did with the Iraqi prisoners?
 

Re:First mistake (1)

Fred_A (10934) | more than 8 years ago | (#14513256)

An obscure punctuation mark which doesn't exist BTW.

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 Amazon link) which apprently is also popular in the US for further insight on punctuation mayhem in English.

Disclaimer: I'm French, I just happen to speak English, sorry about that.

Re:First mistake (1)

heavy snowfall (847023) | more than 8 years ago | (#14514120)

I don't really care if you embed an aff code in the link, but why claim you're not when you are? /ref=pd_bbs_1/

Re:First mistake (1)

Fred_A (10934) | more than 8 years ago | (#14517349)

Because I'm not. Typing a title in the Amazon search bar of Firefox to find an URL doesn't magically produce affiliate codes.
Grow up.

Re:First mistake (1)

fwoggey (538973) | more than 8 years ago | (#14514576)

Doesn't exist?! What?!

Re:First mistake (1)

petermgreen (876956) | more than 8 years ago | (#14526246)

well it got enough acceptance for unicode to accept it and ms to ship at least one font that includes it with office and one font that includes it with windows.

craigslist (1, Informative)

Anonymous Coward | more than 8 years ago | (#14509221)

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... (4, Insightful)

afabbro (33948) | more than 8 years ago | (#14509267)

...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?

Find a tech writing 'guild' (1)

ghostlibrary (450718) | more than 8 years ago | (#14509301)

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 the online part of these groups is talking with peers, but they sponsor events where writers can meet editors-- and that's where you get work.

Plus, being a member is handy to list on resumes, shows you take your work seriously.

Someone else mentioned Craigslist, that's not bad for one-shot tech writing. If you just need to get some clips (samples of paid published work), WritersWeekly is a newsletter that lists poor-paying work by desperate companies (well, that's my take on their ads) that can at least get you some samples.

Also check magazines that cover your field, as their classifieds often list calls for work. You can check their online editors or just spend an afternoon at a decent library.

Then again, maybe open calls to /. work. Hey, hire me to! I do tech _and_ science writing! Visit ghostlibrary.com for details! *plug* *plug*

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

Anonymous Coward | more than 8 years ago | (#14509816)

Hopefully you can find a guild that doesn't have unreasonable entry requirements [slashdot.org] .

It isn't an open call... (1)

Interrobang (245315) | more than 8 years ago | (#14511054)

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 organization you mention, not because I do science writing, but because they probably know something that would be useful to me.

As it stands, I'm networked in with the local STC [stc.org] chapter, the local IABC [iabc.com] chapter, belong to two technical writers' mailing lists (TECHWR-L [techwr-l.com] and Techshoret), and I am also networked into the local small business community through the London Small Business Centre [sbcentre.ca] and Fanshawe College [fanshawec.ca] , where I instructed for a term. However, while that gives me an excellent local grounding, it doesn't do much for wider exposure. Since most of my clients are not in the local area at this point, I now need to focus more on expanding my network outward nationally and internationally.

While I find the local exposure has been good for me, it's useful to have concrete examples of stuff I haven't yet found in my wanderings (you folks collectively can and have hit a lot more sites than I), and it's always useful to have different eyes looking at any given problem.

Re:It isn't an open call... (1)

nacturation (646836) | more than 8 years ago | (#14512613)

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.
 

The words that describe the output of your work. (1)

stienman (51024) | more than 8 years ago | (#14509318)


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 terms of what you 'sell', or the expected output of your work:

Document, manual, quick start guide, etc.

Then I'd move on to what kind of work I expect you to be doing:

Editor, editing, illustration, diagram, explanation, explain, etc.

Then I'd write it myself, pass it around to my friends, and focus on making a better product instead of paying someone to do something that I, a stupid person, could easily and readily do.

Quite frankly, however, I'd suggest that you carfully choose how to represent yourself. If you really want to work with people who have now idea how you fit into their process, you're only going to make your job very hard, and typically (unless you can truly educate them so they understand your value) they won't want to pay you what you're worth.

Take it slow, and go for those people who know what role you are going to play. There's still a ton of work you'll need to do in educating even these customers, but you'll find yourself spending more time working on the project than working on the customer.

-Adam

Seriously... (3, Insightful)

aphoenix (877085) | more than 8 years ago | (#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 (1)

MarkusQ (450076) | more than 8 years ago | (#14509688)


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 dedicated "documenters" because, no matter how good they are at writing, the results tend to be vacuous unless you can get them really engaged with the product. Instead, I tent to look for writers who will also do tech support or testing, so that they get a real feel for the product rather than just regurgitating a grammatical paraphrase of what the engineer told them over the cube wall.

I tried the documentation / sales force combination once, but wound up not using any of the results until the following April, when we used a few sample paragraphs and our lawyer's attempt at a rewrite in an April fools memo.

--MarkusQ

Re:If Google was up to it (1)

hcdejong (561314) | more than 8 years ago | (#14517890)

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 a writer with a technical background than one with a language/psychology etc. background.

Re:If Google was up to it (1)

MarkusQ (450076) | more than 8 years ago | (#14520153)


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 users, and, in short, get their hands dirty if they're really going to write about it well.

There's a fundamental rule here: you can't write what you don't know, and the quickest, easiest way to learn something is immersion.

--MarkusQ

Re:If Google was up to it (1)

hcdejong (561314) | more than 8 years ago | (#14521076)

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 job is to write TFM. That's usually a full-time job, there's no time left to go play tester/tech support person.
4. I, for one, would hate being made to do tech support for the products I write manuals for. I'd be going BOFH on the poor customer in no time. If I wanted to do tech support, I would have applied for a job in that department.
IOW, a sportswriter can cover a game perfectly well without going to the practice session and play being quarterback.

1: yes, IAATW (I Am A Technical Writer)

LDP (2, Insightful)

jnik (1733) | more than 8 years ago | (#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 (1)

Apreche (239272) | more than 8 years ago | (#14509866)

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 lots of HOWTO: type stuff on a blog somewhere and get your stuff up on digg and slashdot every week. Someone who needs writing will be sure to notice.

Search Terms (1)

druzicka (314802) | more than 8 years ago | (#14509891)

what kinds of search terms would you use?

symbiotic parasitic life-forms

Look for "C /C++ / Fortran Information Developer"s (0)

Anonymous Coward | more than 8 years ago | (#14509894)

As per this job posting from IBM looking for technical writers, disguised as a job posting for compiler developers:

Description

Your Environment:

The IBM Toronto Laboratory is one of the largest software development sites in IBM and the fourth largest R&D facility in Canada. A dynamic team of 2,500 highly skilled professionals, who develop, test, service and market our software products, are among the most talented in the industry. The Toronto Lab has worldwide missions within IBM for database management, application development tools, electronic commerce, and business components. These software products run on all IBM systems (xSeries, iSeries, pSeries, and zSeries) using a wide variety of operating systems, including AIX, Linux, HP-UX, Sun Solaris, Microsoft Windows and z/OS.

Your Team:

Compilation Technology Development develops and maintains leading edge C, C++ and Fortran compilers that enable businesses to develop their mission critical applications or products. These compilers are available on AIX and Linux on POWER. In addition, the C and C++ compilers are available on OS/400 and z/OS.

The C, C++ and Fortran Information Development team delivers documentation for IBM's XL C++ products and for XL Fortran products. Examples of the documentation written by the team can be found at http://www.ibm.com/software/awdtools/xlcpp/library / [ibm.com]

Your Role:

This Information Developer position offers an opportunity to collaborate with developers, testers, service analysts and other technical writers at IBM's new software development facility in Markham, Ontario.
Using skills in writing and organization and applying your technical aptitude to a product under development, you'll contribute to a future release of IBM application development tools and compilers; products that provide the foundation for e-business.
The work will allow you to gain exposure to object-oriented languages and compiler technology. You will also be using leading-edge technologies and tools to produce your information deliverables.
This position requires strong English writing skills and a proven ability to understand and explain highly technical information from design documents,architecture documents and product drivers in progress. Knowledge of one of C, C++ or Fortran languages; Unix, z/OS, USS or Linux operating systems is required. To be successful, you must possess strong writing skills and a proven technical aptitude. It is essential that you have the ability to take initiative, and always work in a pro-active manner with colleagues at all levels.

Be proactive (2, Insightful)

spyrochaete (707033) | more than 8 years ago | (#14509938)

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.

Re:Be proactive (1)

Grab (126025) | more than 8 years ago | (#14511461)

Now *there's* a surname you want if you're a kernel developer...

Grab.

Put up posters on college campuses (2, Funny)

dheltzel (558802) | more than 8 years ago | (#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?

Relevant Technologies (1)

conJunk (779958) | more than 8 years ago | (#14510494)

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.

Re:Relevant Technologies (1)

hcdejong (561314) | more than 8 years ago | (#14517915)

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, and yours in particular. Fortunately, many tech writers use CMSs on a daily basis. Imagine that: you may learn something from the writer in the process.

Why hire a technical writer? (2, Insightful)

Ark42 (522144) | more than 8 years ago | (#14510677)

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.

Re:Why hire a technical writer? (1)

Z0mb1eman (629653) | more than 8 years ago | (#14511094)

I take it you've never worked on software developed by a team larger than 2-3 people?

Re:Why hire a technical writer? (1)

Ark42 (522144) | more than 8 years ago | (#14512778)


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? (1)

jilles (20976) | more than 8 years ago | (#14511423)

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.

Re:Why hire a technical writer? (1)

Ark42 (522144) | more than 8 years ago | (#14512808)


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? (1)

99BottlesOfBeerInMyF (813746) | more than 8 years ago | (#14512353)

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 often also functions as a first line of customer advocacy. If they can't figure something out, the interface is probably not intuitive and should be reworked. On smaller projects a writer can save you a lot of time by simply doing a first pass at writing a manual for a piece of software and explaining all of the things that are obvious to a savvy user, but maybe not to the average user. This could easily be 75% of the work, leaving you to fill in the blank 25% that they don't grok.

Other advantages to hiring a professional is that they should be familiar with layout tools for making print versions of documents, and methods of taking a single source file and outputting various types of documentation including print, PDF, help systems, man pages, and HTML. At least one good tech writer is pretty much a necessity if you want to output professional looking products.

I hope this perspective, from someone who has done a fair bit of coding and writing, is helpful to you.

Re:Why hire a technical writer? (1)

Ark42 (522144) | more than 8 years ago | (#14512842)

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 templates, I can generate slighly modified versions suitable for including inside the program, as well as print versions. CHM/PDF/MAN help systems don't really provide most common users any real benefit over HTML, and can at times just make searching the document more difficult. I'm talking only about general small/medium sized applications users may download and install from the Internet, not anything that is going to have several thousand pages worth of documentation when printed.

Re:Why hire a technical writer? (1)

99BottlesOfBeerInMyF (813746) | more than 8 years ago | (#14513376)

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 online help would be useful, like help pages that are searchable and without any grammatical or spelling mistakes.

CHM/PDF/MAN help systems don't really provide most common users any real benefit over HTML, and can at times just make searching the document more difficult.

I don't know where you got this idea. PDF files are printable, something many users prefer (although personally I don't). They also provide better searching capabilities. Try searching an HTML page and then try searching a PDF. The PDF is much faster and nicer. Man pages are very necessary for anything that runs primarily via a CLI and help systems of various sorts are ideal for users who want to look at help but are lacking an internet connection at the time (think mobiles) or who would like to use included help without opening a full browser. Now I'm not trying to argue that all of these apply to you, but they certainly apply to many, many projects.

In any case, good luck with your project.

Re:Why hire a technical writer? (1)

Ark42 (522144) | more than 8 years ago | (#14513885)


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 though is that 1 single document works in 3 different places (online, embedded in an IE sidepane in the program, and printed) with little to no changes or manipulation required.

Re:Why hire a technical writer? (1)

hcdejong (561314) | more than 8 years ago | (#14517992)

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.

Re:Why hire a technical writer? (1)

99BottlesOfBeerInMyF (813746) | more than 8 years ago | (#14518952)

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. With a PDF many viewers (including Acrobat I think) let you see a list of all the instances that match your search at once, rather than slowly moving through each one and rejecting it.

I didn't say that PDF files aren't printable, but that most users won't see any benefit to PDF over just HTML.

Being easily printable is one of those advantages. You can take a PDF to Kinkos and ask for a bound copy and not have problems. Doing the same with HTML is non trivial. Especially given that HTML is generally a whole directory of files, while PDF is a single file you can e-mail to someone.

You may believe HTML works for all purposes, but it does not work well. It is simply not ideal for a help system or for print, and loses the advantages of formats designed for those purposes. I'm not trying to dissuade you from your current practices, but I think you are making a common error in thinking that because you prefer HTML to read documentation, everyone does. This is not the case. Different people prefer different formats and actually use the more advanced features of those formats. Many people would not consider a software offering that does not offer documentation in the standard formats to be unprofessional, and that reflects poorly on your offering. Again, good luck.

Re:Why hire a technical writer? (1)

Fred_A (10934) | more than 8 years ago | (#14513436)

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 I enjoy writing, whether it's in a human or a computer language. I guess most programmers aren't really interested in seeing their work being used. Maybe just solving the problem is enough for them.

I never got to discuss it with the users of the system (although there were plenty of opportunities to do so, I just wasb't interested), bu I had plenty of feedback on my documentation efforts, mostly positive. Later on, in the early 90's when we moved into Internet access, I documented that. There again feedback was pretty good.

Since then I've written a bit of technical documentation, although I mostly stopped those last 5 to 8 years because I'm less and less interested in the computing field (professionally that is) where there is very little return compared to the effort you put into it.

Documentation writers should be technical people with a writing knack. I'm not sure writers with a technical knack can actually pull it off. I've programmed mainframes, minis and PCs ; I've written all my life, I'm more or less at the intersection of those two fields (and others actually). Does it make me ideally suited to write technical documentation ? I don't know, however it certainly helps. Especially when I look at what's available on the market.

OTOH of course nobody ever reads documentation, so this whole rant was pointless.

Re:Why hire a technical writer? (1)

hcdejong (561314) | more than 8 years ago | (#14517942)

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 figure out quite a lot by himself, so there's less need for hand-holding than you think.
Hiring a writer has another benefit: he has a fresh perspective on things, and thinks more like an end-user than most programmers do. A writer can give useful feedback on the UI design and logic of your application.

Re:Why hire a technical writer? (1)

nybble_me (572503) | more than 8 years ago | (#14573088)

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.

Monster or Dice? (1)

stuffduff (681819) | more than 8 years ago | (#14511558)

Maybe it's just as important where you post as what you say...

We don't want your services (1)

jgardn (539054) | more than 8 years ago | (#14512119)

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.

Re:We don't want your services (1)

Mr. Slippery (47854) | more than 8 years ago | (#14513685)

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 salary.

But they aren't... (1)

jgardn (539054) | more than 8 years ago | (#14543262)

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.

Site? (1)

darkhitman (939662) | more than 8 years ago | (#14512403)

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.

Been There, Done That (1)

99BottlesOfBeerInMyF (813746) | more than 8 years ago | (#14512459)

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 at the STC and local universities. Search terms I might include would depend upon the job. If it is another writer to supplement a team I might look for experience with the tools they are expected to use or the particular skills that are needed. I might search for 'Framemaker' or ''internationalization' or 'XML' along with generic terms like 'technical writer.' I might look for experience with similar subject matter, like telecommunications or C++.

All of this is probably not too helpful to you, but given that you did not really describe your goals, it is the best I can offer. Good luck.

Tips for Technical Writers (1)

ipoverscsi (523760) | more than 8 years ago | (#14513442)

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.
  2. Must be able to work with technical people. This means being able to put up with idiosyncratic behaviors, communicating at a technical level, and having a basic understanding of progamming and how developers work. Having had some programming courses in college could help.
  3. Must be self-motivated. I don't have time to hold your hand so you can figure out how to use the software you're documenting. You need to be able to figure it out on your own. You may even need read-only access to the source code repository so you could look things up for yorself.
  4. Must be a good writer. Typos and bad grammar are not to be tolerated.
  5. Have a sense of style. It doesn't matter how good your documentation is, if it doesn't look good it's worthless.
  6. Know your limits. When you find it's impossible to figure something out the software you're documenting, or if it would take way too much time to work out all of the cases, then you can approach the developers. Developer time (particularly uninterrupted developer time) is a vital resource not to be wasted.

Hopefully you might find some of that useful.

Desperately Seeking Documentation? (1)

MikeTheTechWriter (871573) | more than 8 years ago | (#14514827)

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 have ended up really just a loss-leader and vanity project.

Considerations... (1)

warGod3 (198094) | more than 8 years ago | (#14514881)

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.

How to find documentation on hiring editors: (1)

dazlari (711032) | more than 8 years ago | (#14515068)

man oh man
Check for New Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Create a Slashdot Account

Loading...