|
What should be in your Technical Communications portfolio?
The quick answer to the question 'what should be in your technical communications portfolio?' is 'whatever it takes to get you hired.'
The longer, more helpful answer depends on the audience for which you will create content. In the software industry, there are three main kinds of content — procedural, conceptual, and reference. Hiring managers typically look for evidence that you can create all three when they evaluate Technical Writer candidates for staff positions. The exception is when the job involves only one kind of deliverable, typically reference documentation, because Technical Writers who can do that well are in short supply.
Three types of software documentation
To avoid confusion, here is the purpose and context for what we refer to as procedural, conceptual, and reference documentation.
- Procedural content helps users accomplish discrete actions, and in the software industry is usually associated with "end-user," how-to instructions that assume little or no technical sophistication or analysis on the audience's part.
Good examples include manuals for consumer products such as word processors, spreadsheets, and tax-preparation software. Another term for end-user software documentation is "GUI doc" because it tells readers where to click and what to type in the graphic user interface. Outside the software industry, Technical Writers create procedural content for everything from consumer electronics (eg, cameras, TVs, MP3 players, and alarm clocks), to organizational 'best practices,' to pre-flight checklists for aircraft.
- Conceptual content helps users understand a complex process or technology. Concepts often appear in conjunction with procedures, but unlike procedures require the reader to analyze a situation or use his or her imagination. Conceptual content requires the content creator — whether it be a Technical Writer, Instructional Designer, or Graphic Designer — to have a much deeper understanding of the subject material. In the software industry, conceptual content usually appears in documentation explaining how to install, configure, and administer complex networking or enterprise application products.
A classic example of conceptual content is to compare the operation of networking software to an old-fashioned, operator-assisted telephone switchboard. The metaphor of a human telephone operator receiving requests and making deliberate connections between telephone users via the switchboard helps readers quickly envision the product's role. Different networking protocols can be understood as different human languages requiring either foreign language-speaking or multi-lingual operators, and so on. Although the metaphor suffers when analyzed much further, it helps with comprehension and provides context for the procedural content it accompanies.
- Reference content helps users fully utilize a product. It is seldom read sequentially or completely, so relies on consistent structure and detail, as well as accessibility, to be useful. To create effective reference material, the content creator must have a deep understanding of both the subject material and the needs of the audience. Content creators who lack the requisite subject matter understanding tend to create inaccurate or incomplete content, and those who don't understand their audience create content that is irrelevant.
In the San Francisco Bay Area's software industry, demand is strongest for Technical Writers who can create API reference documentation. Although not nearly as 'creative' or nuanced as good conceptual or procedural content, API references are crucial because they detail how two products can 'talk' to each other and thus make each more valuable. An effective API reference helps software developers combine or 'interface' the documented product with their existing computing infrastructure, or products from 'partner' companies, to best effect. To create an API reference, the content creator must know:
- what the documented product does, in detail
- what a typical interfaced product (eg, a relational database, business intelligence application, or document management system) does, in somewhat less detail, and
- how to read the programming language used to create the API (eg, C, C++, Java, or C#).
To help developers more easily implement software that integrates the documented product, API reference content creators should also know how to write short, illustrative programs using the same language.
Outside the software industry, technical communicators contribute to reference content ranging from equipment maintenance manuals, to specifications, to the Physicians' Desk Reference and wikipedia.
How to prove you can create software documentation
Managers hiring technical communicators review portfolio samples for evidence of candidates' ability to write well, present relevant information clearly and concisely, and meet the needs of a specific audience. All else being equal, however, they prefer previous experience with their subject material, which (they tell us) proves that the candidate knows what to tell the audience and how efficiently to gather that content. When the hiring manager is an engineer or the hiring decision is heavily influenced by the perspectives of engineers, a candidate's experience with the company's technology and audience is a much more significant factor.
As a candidate, assuming you haven't worked with a given company's product before or created content for its specific audience, the role of your portfolio samples is to show that you can create something comparable. To do this, gain some understanding of the product and the documentation's audience then explain — in a cover note — their similarities with your prior experience. Our Catch-22 article gives examples of how to do just this for entry-level technical communicators, but as a more-experienced candidate you need to persuade the interviewer that you've "been there, done that, got the t-shirt" and that your success on the previous project gave you what you need to do an even better job next time.
But you need to do more than talk. To convince a hiring manager, for example, that you can write developer reference documentation (API references or developer tutorials) when you've never done it on the job, you won't succeed by saying "I can write, and I can learn, so just tell me who to talk to and trust me." Instead, we recommend that you:
- Find out who the company's competitors are and study those companies' documentation for a similar audience.
- Find out which tool they use as their source-control system, to generate embedded doc, and so on — not merely the omnipresent FrameMaker and WebWorks Publisher — then educate yourself about them.
- Find out which programming language the product is written in, then either take an online class in it, read a book about it, or if you already know it, find a friendly developer with whom you can discuss it so you can be sure you sound cogent and informed.
- Find out whether the product interacts with a relational database. (It probably does.) If so, learn — or refresh your knowledge of — some basic SQL commands and concepts.
- Read every word of the company's web site to gain a strong understanding of its goals, products, and services. In particular, read any news releases the company may have posted on its site, and search the web for relevant technical developments so you can discuss them in person.
- Prepare at least five tough interview questions to assess their priorities for your role. Do they want the documentation "good enough and gone" or are they willing to give you the time and SME access to create deliverables that will make them (and you) proud?
- Write some developer reference documentation for a product you already know. Find a plugin for Word, FrameMaker, even your browser by scouring the shareware sites, then write a short (3-5 page) manual documenting its functionality from an engineering perspective (not an end user's or system administrator's). If you can, create short code samples.
The initiative you show by undertaking most or all of the above tasks demonstrates your commitment and makes you a credible candidate. Neglecting to prepare in these ways, and suggesting to your interviewer that your communications and project-management skills will suffice is, in our view, disrespectful to the company and a waste of everyone's time.
What to present
If you have done the kind of work the hiring manager seeks, it's wise to prove it but also not to overwhelm your reader. Bringing a canvas beach bag full of your API reference documentation to an interview may be good for your ego (and your chiropractor), but it's not helpful to most managers. Instead, select your best (that is, least compromised by workplace realities) work and make it available online according to our advice in "Presenting your Technical Communications portfolio." If you absolutely need credit for having written the same kind of document a dozen times, bring along a list of titles you've authored.
A hiring manager in a hurry typically wants to learn whether you can effectively:
- research
- organize
- communicate
- publish
To prove your abilities, it is often helpful to split up and show the following components separately:
- a table of contents
- conceptual material
- procedural material
- reference material
- a glossary
- an index
This way, you can comment on and provide disclaimers to each item independently, as discussed further here.
Finally, if you were not the sole contributor to every aspect of the work you plan to show, make that clear immediately. In such cases, it is often best to isolate the chapters (or even pages) that you created without help — which, in the high-tech industry, is not necessarily the same as having created them from scratch — so that you can honestly claim full responsibility for them.
For additional advice, see our articles on presenting your technical communications portfolio, what to do when your portfolio's content is proprietary, and how to create a portfolio of developer-oriented documentation.
 .  .  .  .  .  . 
|
