Intro to API
... As a relative newcomer to TW (< 5 years), I'd like to ask experienced API writers how one gets started!I got started as a technical-technical writer when, after about 15 years as a programmer, I realized that if I wanted (simultaneously) a life and regular sleep and to earn a good living, I couldn't stay a developer. And, I realized, I could speak and write in English better than most of my fellow-developers. And, I could understand the code and developer-speak much, much better than many of my fellow-tech writers (no offense; they were great at what they did). So, I decided to occupy the niche of
"extremely-technical-technical" writer. I've found that there are many interesting and quite-well-paid projects in that niche. I mostly don't regret my choice. But when I do I write other stuff, sometimes for pay... Or, I go for a walk on the beach.
...I am deeply interested in doing more *technical* technical writing and would have to learn/practice this on my own time. Any tips Emily/Walden/Glenn, et al, could provide would be most appreciated.Contrary to the impression I may have been giving, I do think that reading (and writing) code is one of the best things an API writer can do. And, as you might have surmised, I also think that it's valuable to discuss code with programmers. I try to sit in on code reviews -- where one programmer interviews another about why they made the choices they did in. I learn a great deal about the technology, the tools, and the programmers themselves this way.
I enjoy email lists, particularly TECHWR-L. I also subscribe to a freelance list and a list of computer book writers. I recently joined the framers list.
Specifically, are there trade journals or magazines to which you subscribe (besides those from the STC)?Nope. Literally none. As an occasional contributor to the mass-market technical press, I've come to be really skeptical about most technical journalists. When I read what is written about some of the companies I've worked for and about some of the products or product areas I've worked on/in, it becomes clear to me that, at best, there's not enough substance in these for me to bother reading them. If I am researching a particular topic, I use Google and pull up every article I can that's on-line and read as many as I can.
I belong to NWU not STC. I have found quite a few cool jobs using the NWU job hotline and NWU is very reasonable about commissions, payment terms, etc. NWU also offers great deals on health and liability insurance. And, their annual fee is low compared to other professional organizations. On the other hand, I don't avidly read their publications and I almost never get to their meetings. The will is there, the free time is not. NWU is the National Writers' Union; they don't specialize in technical writers. They get all hot and bothered about all kinds of political and other stuff, most of which I don't get involved with. But the technical writers of NWU seem to be a cohesive and supportive little group out here on the left coast. Oh, and one other thing about NWU. They really will try to support you when a client stiffs you, particularly when you've gotten the referral through NWU. This does happen and usually means you don't get paid for at least the last 30 days of work, for a while at least, plus you are all-of-a-sudden out of a job AND you can't use the folks who are refusing to pay you for a reference, now, can you? That's another really nice thing about being friends with the developers, btw. Usually, the person to whom I submit invoices is some writer who writes about kitchen supplies or something in a building far, far away from where the techies sit. My manager frequently has not a clue what I am writing about or whether I am doing good work or not. So, I try to keep in touch with the developers and can usually get a good reference from them, even after the client's check has bounced. (Do I sound cynical? Just you wait, Kelly. My advice is: get a retainer for the last month IN ADVANCE. Landlords do this with tenants...)
Are there helpful web sites?Well, I do a lot of PHP and HTML development and use a variety of Web sites for information about these tools. I am frequently tempted to submit suggestions for improvement of the documentation of these products, but I almost never do :-) I don't usually have questions about the languages themselves, but when I do, I mostly consult one of my dust-covered language reference manuals. The hard-bound, hardcopy kind. Or, if it's Java and I really can't figure it out, I look on Sun's Web site. A few years ago, I frequented Hotwired a lot but lately I don't have time and maybe have gotten beyond that level. Hotwired has good tutorials on Internet-related things like PHP, Javascript, etc.
Did you take programming courses or are all of you former developers?Recovering programmer; often relapse. If you haven't worked as a developer before, I would definitely recommend that you take at least a course or two in a particular programming language. If you don't like programming, puzzling out what particular and complex lines of code do and figuring out why one would implement a program one way but not another, I don't think this is the niche for you.
P.S. I have an excellent relationship with the developers at work (although I currently work with them little), and self-sacrificing, sleep-deprived masochist is my mantra!One of the things I discovered as a programmer was that one actually does much better work if one is not sleep-deprived. When I can't sleep, which does often happen, I work -- no point in wasting time. But if/when I CAN sleep, I do and I think my work is better for it. On the other hand, I am not particular about WHEN I sleep. So, fairly frequently, I'll find myself carrying on an email conversation with a programmer at, say 3 a.m. It lets them know that I "feel their pain". Not a bad thing for our relationship. And, I DID use to feel their pain all the time, so I know what extreme lack of sleep feels like. I just ALSO know that lack of sleep is not conducive to intelligent decision-making or quality programming or quality tech-docs.
Oh, and one other thing. As the tech-writer in the tech-writer/developer relationship, you mostly need more from the programmers than the programmers need from you. That can change the dynamic between people who've known each other in other contexts before. Not saying you can't still be friends. Just saying it changes your dynamic. And, if they knew you BEFORE you got really techie -- well there is the macho thing to overcome. Again, you might want to over-compensate by getting a fair amount of programming experience before making the transition. Or else, find a new workplace in which to establish your new high-tech persona.
--Emily
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~ Emily Berk ~
On the web at www.armadillosoft.com *** Armadillo Associates, Inc. ~
~ Project management, developer relations and ~
extremely-technical technical documentation that developers find useful.~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline April 27. http://www.pdfconference.com.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
Previous by Author:
Re: YOWZA--struck a nerve: Was Help API Documentation?
Next by Author:
Hotkey standard
Previous by Thread:
Réf. : Re: "install" as a noun?
Next by Thread:
Re: Intro to API (Was: YOWZA--struck a nerve: Was Help API Docume ntation?)
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads