Note: This file has moved to notablog.

A friend asked me:
> Interesting. I am at a similar crossroads in my career in that
> programming is becoming more and more attractive as my job duties
> become more and more technical. How did the transition go for you?
 
     It's certainly a possible career option.  I know far more
failed-tech-writer-turned-programmer than vice versa, including
myself.  There are a lot of "ifs" to the situation, however, including
your character, drives, needs, the kinds of languages you're thinking
about getting into, what kind of foundation you already have, etc.
  
     There are a few general things I can say.  This is all, of
course, based on my limited knowledge of and exposure to the field.
First, go read my map of the
career field.  I'm going to make broad, sweeping generalizations
and strong, declarative statements, because otherwise I'll be here all
night and this document will be four times longer and much less fun to
read.  Take it all with a grain of salt.

     First, before you get discouraged, not too long ago I came across
a statistic saying that only 1 in 5 working programmers actually has a
degree in a programming discipline.  The programming field needs all
kinds of knowledge and all kinds of individuals.  So take heart.

Systematic Knowledge vs. Idiosyncratic Knowledge

     Something I've noticed is that there seems to be two kinds of
expertise, and people seem to tend to have a mind that works for
either one or the other.  I'll call the two type systematic and
idiosyncratic.

     Systematic knowledge is knowledge about a topic that has an
underlying structure, knowledge that follows a pattern.  Not only does
a given topic area have its own pattern, but the patterns themselves
have similarities between topic areas.  System programming languages,
for example, often have such structural similarities.  If your mind
clicks with systematic knowledge, then as you recognize the structure
of the topic you're studying, like pieces of a puzzle coming together,
you'll start to "get" the topic and find learning more and more about
it becomes faster and easier.  

     Also, as you go from one topic to another, common structures will
help you acquire a new topic faster.  A really good programmer can
learn much, if not most, of a structurally similar programming
language in an amazingly short time.  It's going to be in tackling
radically different languages (like a procedural language vs. an
object-oriented language vs. a functional language) that you'll hit
the major speed bumps.  Consequently, really good programmers tend to
like to seek out such new experiences, to broaden their arsenal.

     Idiosyncratic knowledge, on the other hand, has lots of special
cases and exceptions.  It doesn't follow a pattern as much.  There is
structure, but it's nowhere near clear or elegant.  The real world
isn't often clean or elegant.  The original name I was using for this
type of knowledge was automobile-repair type knowledge.  Car repair
and car parts are a good example of this sort of thing.  The topic is
loaded with little "gotchas" and tidbits of important knowledge.  If
you have a mind that likes to master this sort of thing, then you may
find there are several lucrative specialty areas of the technology
industry that you'll be well-suited to.

     Personally, I consider personal computers and Microsoft Windows
products to be a prime example of idiosyncratic knowledge.  Why this
is, I won't speculate here :-).  I also consider many 4GLs ("4th
Generation Language", a phrase usually only used by people who work
with them a lot and by marketing droids) to be extremely
idiosyncratic, usually because they weren't so much designed as
accreted, influenced by marketing and sales imperatives to add this
feature or that buzzword, or often by the need to support a wide
variety of legacy systems.

     However, I suspect you could also make a strong case that a lot
of Unix system adminstration details qualify as idiosyncratic
knowledge.


Domain Knowledge vs. Discipline Knowledge

     Programming is pretty much always about trying to build a
working, electronic model of something.  The model is usually of
something that exists at least partially in the real world (though
often that real world existence is mostly a political or economic
fiction).

     Discipline knowledge is the knowledge of programming, system
design, etc, I've been referring to all along.  Most working
programmers also need to have (or over the course of a specific
project acquire) some degree of domain knowledge as well.  Domain
knowledge is knowledge of a particular subject or topic related to the
model.  As an example, consider a programmer working on an accounting
package.  He or she has to understand bookkeeping and other standard
accounting practices in order to implement a proper model of them.

     Domain knowledge also comes in more than one flavor: technology
domain and business domain.  The technology domain knowledge is
knowledge about a specific domain (for example, java technology as
opposed to object-oriented programming knowledge).  The business
domain is knowledge about a specific business, industry, profession,
etc.

     In general, I feel a programmer's discipline knowledge is (or
should be) much more important to his or her career than their domain
knowledge, but then again there are a great many people out there who
aren't looking for the same things I'm looking for in a career.
They're quite happy in taking advantage of their domain knowledge and
leveraging it to enhance their career.  Certainly it's a quite useful
tactic if you're just getting into programming.  However, just as a
technical writer is more than a glorified typist, a programmer is not
the sum of the programming languages and development environments he
or she has worked with.  Programmers deal with many of the same issues
that technical writers deal with, in this regard (being typecast due
to previous experience).

Your Challenges

     I started writing this to answer a question from a technical
writer I know (since I used to be a technical writer and now I'm paid
to program).  

Computer Theory 

     Depending on where you want to go in your programming career, I
suspect you're going to find lack of computer theory knowledge to be a
constant issue.  Most Computer Science graduates have long forgotten
most of their theory, but there are still fundamental concepts that
they had drilled into them, things they take for granted, that I need
to learn.  This becomes particularly evident because of one of my
strengths as a technical writer - the fact that I'm good at
researching new areas.  I tend to dive in head first, and sometimes
that flat out just doesn't work, because I'm not just tackling new
details, but fundmentally new (to me) concepts and theory.

Right-Brain Thinking

     I am firmly convinced that certain kinds of programming languages
and certain kinds of programming activity are extremely right-brain.
I'm thinking mostly and particularly about system programming
languages and object-oriented languages.  

     This is not to say that the programmers who specialize in them
are all creative, artistic souls.  Indeed, hand in hand with that
right-brain, geometric-problem-solving type of activity comes a need
for excruciating attention to detail and constant analysis.  This,
needless to say, is not easy, particularly if, like most writers, you
have strong left-brain analytical and language skills.  It can be very
difficult to develop and sustain that "hack mode" focus.

     I have to emphasize that this is not the same as concentration,
although concentration helps.  A friend once described it as an almost
autistic state of mind.  Certainly, everybody has moments of this
state of mind, but certain kinds of programmers have to spend solid
hours every day, most of the day, in this state of mind.  I find it
very enervating.

     I also find it quite annoying, in that it destroys my ability to
be coherent and detail-focused.  When I'm interrupted in this state of
mind, I find it difficult to form coherent sentences.  After a day of
being in this state of mind, I have trouble focusing on the mundane
details of my life, figuring the various things that need done and how
to go about doing them.  While I find the mind state itself somewhat
thrilling, I quite dislike the resulting effects on me.  I like being
who I am, and I like being able to be coherent and competent in
everyday situations.
     

Your Advantages

     As a technical writer, much of what you do on a daily basis is
not about writing, per se, but about the things you do to support your
writing.  Surprise, surprise, that's true for programming as well.
It's especially true in certain niches in the programming career
field.  Some of your "tech writer" skills will give you strong
advantages, particularly when you're using them in jobs that have a
strong focus on programming to solve business problems.

Communicating Complicated Technology

     As a technical writer (emphasize the word "technical" here") a
big part of your job is to communicate complicated technology
knowledge to non-technical people.  As a programmer in a business
context, you can put these talents to good use going in the opposite
direction.  Your job will be to take a business situation and
translate that into a technology context, and come up with ways to use
technology to improve the situation.  Unless you happen to be a master
of the business context at hand (the domain knowledge), this process
is going to be more of a dialog with the non-technical business users.

     You'll also have a strong need to communicate the technological
issues back to the business users.  There's a balancing act that goes
on here.  On the one hand, most of the time, the business users don't
even know where the ballpark is, let along where they are in it.  You
need to provide them with enough orientation that they can make
business strategy decisions based on your investigation of technical
issues.  You have to do it concisely, and you have to do it as
non-technically as possible.

     However, on the flip side, far too often, the technologist
responds to a question of "what should we do?" with a description of
the pros and cons and the alternative strategies that can be used...
and the business users' eyes glaze over because they don't really need
more details to worry about, they just want this problem to go away
(either because they lack the brainpower to deal with it, or much more
likely, they have plenty of details to deal with already - see my comments
about right-brain thinking, above).

     The business users will want the response to address the
situation in a language they can understand, and they'll want any
decisions that they need to make to be phrased in a business context.
For example, "there are a couple of alternatives.  To decide which one
is best, I need to ask you to set some priorities..."

Document Production

     On a more cynical note, in quite a few business situations, your
ability to churn out written documents will come in handy.  Since much
of the work you'll be doing as a technologist will be skull work,
written documents, overviews, system diagrams and plans of attack can
often be extremely useful in a political sense.  Since a lot of time
goes by while you investigate, research, and contemplate, it can be
quite difficult for the business user to get a sense that anything is
going on.  By producing written works that summarize your skull work to
date, you both inform the business user (in the rare event that they
read it) and you reassure them that you are, indeed, making progress.

     In rare situations, your ability to write clearly and to
communicate will actually be a boon.  As writers we often forget just
how poorly written most documents are.  One thing not to underestimate
is the power of a diagram to illuminate a complicated technical point
to a business user.  Obviously there's a balancing act, but diagrams
can help make the abstract seem quite concrete.

     In situations where you're working with a team of programmers,
written documents can also be crucial in creating a common context,
making sure everyone is on the same page.  There are some classic
quotes in Fred Brooks' _The Mythical Man Month_ about written
documents having two crucial effects.  First, they require you to make
many little decisions that you've been putting off until now.  Not
that they're necessarily important decisions, but it's important that
they be made, and that they be made consistently.  Second, they
communicate explicitly the many things that various members of the
team assume are common knowledge.

Research 

     As a writer, and as a technical writer, some of our strongest
skills are in research.  We tackle new topic areas and absorb them
quickly.  We know how to learn, we know how to ask the right questions
and we know how to record and remember the answers.  This has positive
implications both in career development, and on specific jobs.

     In career development, you'll probably find an endless wealth of
information about your new career.  You'll never want for something
new to learn.  This is really one of the most daunting things about
programming, particularly if you choose a career path that takes you
into the more general programming fields.  Programming is used for
damn near everything these days, which means there's a ton of special
knowledge for any given technology domain, as well as any given
business domain.  

     Java is one of the better examples for this, I think, probably
due to the fact that Sun is trying to jumpstart the java industry by
tackling the many different sub-industries that have evolved to suport
various technology domains in C/C++ (and to some degree Smalltalk)
over the past twenty or more years.  As a result, java has many, many
different class library API reference implementations - areas where
Sun has laid out the foundation for further work by other people in
the industry, and provided both a standard for interfacing with tools
to support those areas, and a "reference implementation" as a good
working example of how to build those tools.

     In addition, most programmers have to do some amount of business
domain research, frequently, to inform and shape their software
projects.  As a technical writer, you'll probably be more effective at
walking into completely new situations and getting a grip on it.

     Finally, in many very large business contexts, the "journalistic"
side of your technical writing experience will come in quite handy.
Many very large corporations have very muddled organizations and
little to know formal investigation and tracking of their knowledge
assets - they don't know who knows what, and they've often forgotten
how to figure it out.  

Two anecdotal examples:

     At one organization, the question came up of how to get some data
from a mainframe system out into a Unix system.  I was probably the
only guy in the room who did NOT have significant mainframe
experience.  However, the other folks in the room just kind of shrugged. 

     So I asked, "Well, who knows about ?"

     "Bob does." 

     "Okay, I'll follow up on this with Bob."

     After the meeting, I track down Bob and ask him how to get the
data out.  He says, "Well, I think Linda knows about that data."

     I track down Linda and ask her about it, she keys in a few
commands in the mainframe application she uses and shows me a listing
on screen.  "Do you want me to print this?"

     Since it's several thousand rows of a database table, I don't
really want it printed, I want it on disk, so I don't have to type it
in.  

     Linda says, "I don't know how I'd do that."

     "Well, who would know?"

     "Maybe Ed."

     So I track down Ed, and I ask him how to do it.  

     Ed says, "Well, the first step would be to get it out of the
table and (tech tech tech tech)."

     "Okay, how do we do that?" 

     "What region is it in?"  

     I run back to Linda and get her to write that down, and bring it
back to Ed.  Ed checks and says yeah, he could dump that out for me.

     "And how would I get this onto a floppy disk?"

     "Alan might know that."

     So I track down Alan and ask him, show him the identifying
information, and ask him if he could get it out to disk.  Success!  He
can indeed put it on a disk for me, if I'll ask Ed to dump it out
first.  I do so, Ed does so, Alan does so, and I go back to my boss
with the data safely in the Unix system where we need it.  All at the
cost of 30 minutes of walking around and talking to people, and asking
the obvious questions.

Second Example:

     At another organization we put together a set of web pages, forms
and scripts to allow potential customers to apply for a service.  One
problem - what do we do with the application?  How do we get it into
the system so it can be processed?  Well, of course the system the web
site was running on was a Sun Solaris (a flavor of unix) server.  The
system the appliction processing was done on was a mainframe with
3270-style terminals.

     So three of us are standing there, talking about this, and the
question comes up: how do we get the applications into the system?

     Blank stares from the other two (highly intelligent, generally
skilled and not technically incompetent) people.  

     Finally, I hesitantly ask: "Well... how do we get the
applications in now?"

     "I think the call center ships a magnetic tape out every week."

     "Okay, then let's see if we can do the same."

     A quick phone call later we learn that in fact, all of the calls
are routed to the call center in another state, which is located in
the same building as the mainframe.  The call center employees then
manually key the data in on terminals connected directly to the
mainframe.

     Again, blank stares.

     "Well... do we take over-the-counter applications?"

     "Yes."

     "And those are written on paper?"

     "Yes."

     "How do those get into the system?"

     A quick phone call later, "We fax them to the call center."

     Well, it's painful, but I have to admit that we eventually set up
a system that took the application data from the web page forms and
generated a fax to the call center, as a short-term solution while we
set up a more complicated system.

And the moral of the story...

     The point of these stories is that technical writers get used to
having to find a way to what we need.  We get used to assuming that
there is an answer, but we just don't know it, and we get used to
asking questions until we have an answer.  The people I was working
with were smart and competent, but they weren't used to having to go
around problems instead of through them.


Project Management

     Technical writers are usually used to bearing the primary
responsibility for managing their own projects, and they're used to
usually being the sole writer on a team (or sometimes in a
department!).  As a result, tech writers tend to develop good project
management skills.  These skills can often be further developed to
general project management.  There are many gotchas to worry about
here - software projects are the very personification of the
difficult-to-manage project.  But in general, technical writers will
have an edge in the project management area, and should develop and
extend this edge as much as possible.

     Much of JoAnn Hackos' _Managing Your Documentation Process_ is
based on or informed by project management research done by the
Software Engineering Institute (SEI).  If you've read her book, that's
a good start.  I'd also generally recommend getting and reading other
documents on the topic, both from the SEI website and by subscribing
to the _Communications of the ACM_ and _IEE Software Development_.
You should also check out Steve McConnell's books, _Code Complete_ and
_Rapid Development_ (McConnell's personal web page is at
http://www.construx.com/stevemcc/).

     Having said all of the above, I must again caution the technical
writer against being too confident in your project estimating
abilities.  As I mention above, programming is about building a model
of something in the real world.  The problem is, the real world is
vast and complex, ever-changing on both the micro and macro levels, at
varying rates.  Equally our understanding of the real world is
ever-changing.  By the time a software project is complete it's
usually inaccurate, or irrelevant, or both.  Most often the project's
outcome is some traffic pile-up combination of good and bad, with
something eventually going out the door but not necessarily what the
end-user needs.  

     So what to do?  My best advice is to avoid having to be
responsible for the bottom-line committment, at least until you have
more experience under your belt.  Ideally you should use your skills to
help facilitate a more experienced project leader's project planning,
and learn from him or her in the process.  Very often, where novice
programmers get into trouble with schedules it's because their initial
assumptions were incorrect, or because their superiors (often
non-technical superiors) change the base assumptions on them.  Often
the novice gets pressured into making tenative committments based on
tenative assessments of problems and risks, and as soon as they're
made, the non-technical superior nails them down and assumes they're
set in concrete.  

     One thing I've noticed is that nobody ever remembers the
qualifications, everybody always remembers the due date.  One tactic,
nice when it's feasible, is to do an initial functioning prototype
before giving a schedule committment.  By that point, ideally, all of
the unknowns are explored and what remains is mostly tactical work,
things that are extremely predictable.  But be careful, prototyping
quite often leads to the business superior deciding to deploy the
prototype instead of waiting for the finished product.

     If you have to take the point on the project plan, my advice is
to avoid big committments to a bottom line.  Instead provide a very
well-fleshed out project plan and schedule.  Keep it constantly up to
date, on a daily basis, and reissue it, pointing out where changes
have changed the projected project completion date.  Use that as a
basis for discussing whether the date should be changed or some
element of the project should be put off.  Be extremely careful about
letting the business user lead you into situations where they demand
you re-estimate some of your estimates downward to allow you to keep
the original due date.

     There are a ton of software project methodologies to deal with
this problem.  One of the approaches I like best is Extreme
Programming, a lightweight approach to the problem.  You can get
the basics on it at: 

     http://www.c2.com/cgi/wiki?ExtremeProgrammingRoadmap

     By the way, the rest of the c2.com/wiki site is excellent
reading, although a lot of the stuff they discuss is extremely deep
and easier to find relevant to Object-Oriented development situations.
I've been reading it off and on for the past two or three years.  I
was only lukewarm to it at first, but as time has gone by and I've
learned more about the general topic and internalized more of what's
discussed on the site, I've become more impressed with what the folks
at c2.com/wiki have to say.

--------------------------------------------------