GETTING STARTED IN TECHNICAL WRITING

MEETING SUMMARY of the Silicon Valley Chapter of the STC

by Thomas Albert

Andrew Davis, President of Synergistech Communications (www.synergistech.com) explained to a full house
how a newcomer can launch a technical writing career in the software industry. Andrew, with
ten year of experience as a writer and technical publications manager, and three year of experience as a recruiter, shared his
knowledge with candor.

MISSION OF THE TECHNICAL WRITER
Be the User's advocate, the audience's ally. Understand the product, respect its purpose, and recognize your
value in making the product usable. Convey relevant information with precision. Strive for the best quality
possible by the deadline, and stay in touch with technology trends that affect the products you document and the
tools with which you document them.

AUDIENCE AWARENESS
Determine what kind of reader you have, and make the document fit that reader's needs. Major types of
software products in Silicon Valley include the following:

• end-user or shrink wrapped standalone applications, such as Quicken for financial management
• business applications, such as client-server solutions for manufacturing and inventory tracking
• application programming interfaces (APIs) or software developer kits (SDKs) that enable programmers to
  build applications that leverage functions provided in underlying code, such as a graphical user interface to
  facilitate database administration

DOCUMENTATION TYPES
Should you accept the technical writer's mission, you might design, create, update, and revise the following:

• printed manuals, such as user guides and installation guides
• online Help/HTML Help
• Online Documentation, such as Portable Document Type files (PDFs) that allow the user to view and print your document with its original look
• Intranets (internal to the corporation) or web sites on the World Wide Web
• miscellaneous documents, such as release notes about product limitations, marketing white papers, and
  onscreen text, such as prompts and error messages

WHAT TECHNICAL WRITER GENERALLY DO NOT DO
Generally speaking, technical writers do not write the following: trade press articles, scientific papers or abstracts, patent applications, marketing collateral, advertising copy.

LANDING THE JOB
Like any other communications tasks, you start by knowing your audience's needs. Often, the technical publications
manager hires a writer with greater technical expertise in a specific field than the manager possesses. Inform the hiring manager
of why you will be a productive asset to the team. Convey truthfully you level in the following areas:

• subject matter expertise (education is good, but workplace experience is better)
• demonstrated aptitude with the subject material, including your ability to learn quickly
• knowledge of the audience, authoring tools, the information development life cycle, and documentation deliverables
• project management skills (scoping the deliverable, writing the documentation plan, estimating the schedule, managing multiple projects, adjusting as necessary to meet deadlines)
• interpersonal communication skills (ability to be resourceful, flexible, and professional even under pressure; ability to establish rapport with technical personnel and writing colleagues)

PERSONALITY TRAITS
Successful technical communicators tend to have the following:

• curiosity about technology (both products and authoring tools)
• desire to bring order to chaos through the process of writing
• pragmatism (rather than perfectionism that jeopardizes deadlines)
• initiative and tenacity, even when information is difficult to locate or understand
• patience and the ability to maintain a professional demeanor, even under pressure
• imagination: to plan the writing project and to surmise an explanation given incomplete information
• ability to learn quickly and organize that knowledge so the audience can understand it
• respectful assertiveness, the ability to ask for information when necessary
• information management skills: ability to store and retrieve information so that you only need to ask for it once
• the ability to accept editorial criticism so as to improve the written product, and to apply that feedback to your next writing assignment

PORTFOLIO DEVELOPMENT
Demonstrate your ability to write multiple kinds of documentation:

• concepts (explaining how technology works; often this is the high-level view of a process)
• procedures (step-by-step instructions; this is the most common and most essential writing task)
• reference (information for users who are looking for a detail, for example, the functions calls in an application programming interface; often this data is presented in table format)

PORTFOLIO ISSUES
What if you have no relevant writing samples? You can write concepts, procedures, and reference material
about shareware. See www.tucows.com

If you signed a non-disclosure agreement (NDA) that prevents you from showing your work, ask your former
employer if you can show a modified version, or ask your prospective employer to sign a NDA with your former
employer.

If no one person wrote the whole chapter, lay claim to that specific pages that represent your contribution and explain how you, had you been the sole writer, might have made the chapter better.

MARKETABLE TECHNICAL KNOWLEDGE

• e-commerce, such as business-to-business supply chain software from CommerceOne
• structured and/or object-oriented programming (Java, C/C++, Visual Basic)
• scripted languages (Perl, UNIX shell scripting, VBScript)
• software architectures and enabling technologies, such as CORBA and XML
• relational databases, such as Oracle, SQL Server, Informix, Access
• computer networking, such as TCP/IP, the protocol of the internet
• client/server computing, including Enterprise Resource Planning (ERP): SAP, PeopleSoft, and Baan
• customer relationship management (CRM), such as products from Siebel
• software development process, that is, the role of software design, programming, human factors, QA, training,
  tech support, product/project management
• software development tools, such as Visual SourceSafe, ClearCase
• computer-aided design (CAD), such as products from AutoDesk
• electronic design automation (EDA) for integrated circuits, such as products from Cadence and Synposis

MARKETABLE AUTHORING TOOLS

• Adobe FrameMaker, the cross-platform application for long documents
• Microsoft Word
• HTML tagging (it is not necessary to know cascading style sheets, dynamic HTML, JavaScript)
• Blue-Sky Software's RoboHELP, the industry standard Help Authoring application
• Microsoft FrontPage web authoring and site management (or a similar tool)

You should be proficient in at least one screen shot capture utility, but usually you do not need to know how to use graphic illustration tools, such as Visio diagramming, Adobe Illustrator and Adobe PhotoShop.

SPEAK THE LANGUAGE
If you are not an expert, and do not have time to take a class in a marketable area, at least find a book on the
topic and read its glossary or introductory chapter.

FOR MORE CAREER GUIDELINES
See http://www.synergistech.com/develop.htm.