How We Write: Putting the "Technical" in "Technical Writer"
By David Owens
By becoming more technical, you can interact more efficiently with software developers and qualify for a greater variety of software documentation projects. This article outlines ways to learn more about three prevalent technologies: programming languages, databases, and Web server technologies.
Many technical writers bristle at the idea that software developers believe the “technical” part of our job title is an overstatement. We all know that some developers stereotype technical writers as folks who can debate the merits of one space or two after a period or discuss arcane uses of semicolons, but who are lost when the discussion turns to writing code or creating a database. Mastering the technical aspects of the products you document can provide a strong foundation on which to build your work--and it just may give you the edge you need to get your next job or land that plum, high-visibility project you've been seeking. As a side benefit, being able to hold up your end of discussions with subject matter experts may change some developers’ ideas of just how technical a technical writer can be.
If you document software, three technologies you will likely encounter in your job are programming languages, databases, and Web server technologies. To help you develop a working knowledge of these technologies, I provide a brief introduction to each, suggest specific areas to study, and offer a few ideas for doing it inexpensively.
The article is presented through the following sections:
Budgeting Time and Money
The investment of money and time can be the first hurdle in many technical writers’ search for “hard” technical knowledge. Classes, workshops, and conferences in technology are available, but some come with a hefty price tag. Do not hesitate to explore your options; if you can argue that the knowledge you learn will ultimately benefit your employers, your company may be willing to pick up the tab for a class. At the very least, you may be able to take a class on company time. Many resources are available at low (or no) cost, so self-study is also an option.
A fairly low-cost learning option is the O’Reilly Network’s “Safari Bookshelf.” This subscription service allows you to check out ten books at a time to your “bookshelf,” where you can then view the complete text online. For $14.99 a month, you can select from hundreds of books (more are available for a higher monthly rate). Titles cover every technology included in this article and many more.
You may want something more formal to include on your resume or a certificate of completion you can put in your portfolio. Ed2go, an online continuing education provider, offers classes in a wide variety of subjects, including various technologies, through universities and technical colleges throughout the United States. These classes typically cost from $80 to $100 and last about six weeks, with all lessons and assignments conducted online. (Ed2go does not offer its courses directly to the public, so you will have to enroll at an accredited school in the ed2go network. You can find schools offering ed2go classes at www.ed2go.com.)
Budgeting your time is a different matter. We are all pressed for time, and only you can decide how much time you can spare for professional development. Even if it is only one hour a week, however, you will be surprised to find how much you can learn. And if you begin with one hour a week, perhaps you will eventually find more time to educate yourself on the latest technologies.
The better you understand the technology used to create the software you document, the better your documentation will be. This is a somewhat controversial stance among some technical writers, who often assert, “I’m a writer, not a programmer.” While there is no reason you cannot be both, I am not recommending you start gunning for a developer job. But a rudimentary knowledge of programming tools will increase your viability in the marketplace. You will be better positioned to tackle specialized, highly technical projects such as application program interface (API) documentation and software development kits (SDKs) Furthermore, you can increase your value to your company in such areas as testing and quality assurance. For instance, a better understanding of the error messages you encounter in early versions of software may help you provide developers with more specific information when you file change requests. With even a brief introduction to programming languages, you can make mockups of screens and create small applications to demonstrate information delivery ideas.
What Can I Learn?
You'll want to understand the basics of a programming environment so you can communicate more effectively with your colleagues in software development; if you're documenting developers' tools, this knowledge will help you determine what information your readers need. Some rudimentary programming skills--such as developing dialog boxes or forms with controls (buttons, fields, checkboxes, and so on)--can help you create screen mockups that you can use to demonstrate communication ideas such as embedded help. With code-heavy API or SDK documentation, basic programming concepts such as variables and loops, and object-oriented concepts such as classes and inheritances are excellent, if not necessary, things for technical writers to understand. Additionally, learning how to recognize developer comments in code is extremely valuable. Comments may provide auxiliary information, such as the intended function of the code, that you can sometimes use to form a basic outline for your documentation. Finally, if you create context-sensitive help files, you may want to know more about how your particular application calls the help files. Knowing how context sensitivity works can help you work with developers to implement help map IDs and other functionality.
Learning Programming on a Budget
Of course, there are numerous programming languages. The good thing is that many fundamental programming concepts learned in one language are applicable to other languages. One programming language you can learn for a relatively small financial investment is Visual Basic. The Microsoft Visual Basic 6 Working Model Edition comes with most Visual Basic 6 books. The Working Model Edition contains many features you need to get started, but it does not include help files or allow you to create executable files. The Visual Basic 6 Learning Edition includes help files and some other features not available in the working model edition; it usually runs in the $100 range with accompanying books. And don't forget the Internet. Numerous Web sites, including ed2go, are available for newcomers to Visual Basic, many featuring no-cost tutorials.
Because Visual Basic 6 is no longer the latest version of Visual Basic, books that include the Working Model Edition are available at low prices in local bookstores and through Internet booksellers. However, Visual Basic 6 is far from obsolete; it is still a very popular programming environment.
Most developers agree that the learning curve for the current version, Visual Basic.NET, is steeper than that of previous versions, despite the availability of a “standard” edition that is somewhat comparable to the learning edition of Visual Basic 6. To help avoid alienating beginning developers, Microsoft recently announced plans to release an “Express” version of its Visual Studio developer suite. This includes Visual Basic 2005 Express. This version “provides a lightweight experience for first-time programmers and hobbyists.” It includes full access to the .NET framework, as well as starter kits and documentation geared toward the beginner. Visual Basic 2005 Express is currently available in beta and is slated to cost under $100.
Another popular programming language is Java. On the Sun Web site, you can download the Java 2 platform standard edition SDK at no cost. This is a command-line programming environment with no graphical user interface, but it does include the Java compiler and a wide variety of tools for creating applets and applications in the Java programming language. Detailed instructions on how to install and configure the SDK on your computer are available. Additionally, when you register as a member of the Java Developer Community (also at no cost), you can access customized learning paths based on your level of programming experience (including none), and you have access to a library of resources and references to use in Java development.
Chances are, you work with several databases each day –you may even document one or more programs in which a database plays a key role. But how much do you know about how a database actually works – how one is set up and structured? Learning this information can help you document a variety of software products and processes. You can also use databases to make your own work more efficient, perhaps to track documents or usability efforts.
Understanding the inner workings of a database and database connectivity can help you write conversion guides, installation guides, and documentation for database management tools. Database storage and retrieval of information objects is an increasingly popular method of single sourcing in documentation. Learning more about databases can help you understand these methods and apply them to your work. Also, many applications allow users to manipulate database tables using Structured Query Language (SQL) statements –familiarity with SQL can help you document such procedures and provide examples.
What Can I Learn?
You will probably want to learn about different types of databases and how they store information. The most popular type of database for day-to-day transaction entry operations is the relational database. Since most major relational databases use SQL to manipulate data, SQL is a good place to start. It is worthwhile to learn the fundamental structure of relational databases, how to read and write SQL statements, and some basic concepts of data manipulation techniques.
You will also want to know how databases interact with software applications. This knowledge can help you document troubleshooting solutions, and you’ll be better equipped to document installation and database management information for software products. Three of the common interfaces that enable databases to interact with programs are Open Database Connectivity (ODBC), Object Linking and Embedding (OLE), and Java Database Connectivity (JDBC).
You can also learn about multidimensional databases, which can process huge amounts of data very quickly. Multidimensional databases store and process data differently than relational databases, and allow you to compare many different types of data in many different ways. Data mining through the use of data warehousing and data marts is a hot technology topic, and you may get the opportunity to work on such projects. Understanding these databases gives you an advantage in documenting these types of systems.
Learning Databases on a Budget
Numerous resources are available to help you learn more about basic database concepts and SQL. To take most tutorials or online classes on databases, you need some sort of database management system. These systems include Microsoft Access, Microsoft SQL Server, Oracle, and MySQL (an open-source database management system). If you have the Professional version of Microsoft Office, you already have Access – which will suffice for learning about relational databases. If you do not have Access, you can download MySQL at no charge, but if you have no previous experience with it, configuring MySQL can be a technical challenge unto itself.
Again, if you want a more formal setting (or something you can list on your resume), low-cost online classes in database technology are available from Ed2go. These classes include an Introduction to Database Development and an Introduction to SQL.
Web Server Technologies
You probably access the Internet every day. If so, you work with a Web server every day. Perhaps you would like to know a little about what goes on under the hood of that server – about how the information you view and interact with is presented. By learning more about Web server technologies, you will not only be able to document them better in your products, but you may decide to employ them yourself to distribute your documentation on the Web.
One key area of interest for technical writers is using server-side technologies to display documentation on the Web. Because these technologies can be used to customize output based on user profiles and to gather information about whether users are able to successfully find information on Web pages, the ramifications for presenting documentation on the Web are obvious.
What Can I Learn?
Knowing the nuts and bolts of configuring a Web server and the different types of server software can be useful if you need to document installation procedures for a Web-based application. The knowledge can also be a gateway to learning more about Web server security, a sector that is currently garnering massive amounts of attention. Two popular technologies are IIS (Internet Information Services) from Microsoft and open-source Web server software from the Apache Foundation.
You can learn how Web pages are served to a browser and how the browser retrieves information from a server. At its most basic, when you request a Web page by entering the address in a browser, the server sends back the requested HTML page. But through various technologies, the Web is capable of much more. One method of transferring data back and forth between server and applications is called the common gateway interface (CGI). Active server pages (“classic” ASP as well as the more recent ASP.NET) and JavaServer pages (JSP) are more robust technologies similar to CGI applications in that they can be used to customize Web content for a user. Knowing more about all these methods can help you document Web-related software, as well as develop your own Web-based communications.
Learning Web Server Technologies on a Budget
Free Web resources range from instructions for setting up an Apache server, to information about getting started with IIS, to numerous tutorials for using server-side technologies.
The International Webmasters Association (IWA), which has merged with the HTML Writers Guild, offers many resources for technical writers interested in learning more about Web technologies. A basic trial membership in the IWA is free, and a full membership (which is necessary to get many of the benefits) is $49 a year.
For an additional $60 a year, full IWA members may subscribe to a 250-book reference library similar to the O’Reilly Safari Bookshelf, through which books can be checked out and read online. The library covers a full range of Web technologies, including ASP, JSP, and many more. The IWA also offers online classes in beginning JSP and ASP for nonprogrammers. These classes start at $80 for full members.
Finally, don't forget the value of magazines as a free learning resource. Many publications, such as InfoWorld and eWeek, offer free subscriptions to “IT decision makers.” As a professional technical writer, I hope you consider yourself a member of that category. These magazines are geared toward a technically literate readership and frequently feature information on evolving technologies. The areas I discussed in this article are only the tip of the iceberg. Reading these magazines may give you an idea of other sectors of technology on which you would like to focus. For example, wireless networking, security, and enterprise data backup are currently receiving a great deal of attention.
No matter what area you choose to learn about, becoming more literate in technology can benefit your career as a technical writer by qualifying you for new projects and enabling you to speak knowledgeably with subject matter experts. And when you introduce yourself as a technical writer, you can be proud that both words in your title are well represented.
A wealth of resources are available to help you learn more about the technologies discussed in this presentation.
Several resources are included below for learning more about Visual Basic and Java. Of course, these are only two programming languages out of many others you may wish to learn more about.
For most database development classes and tutorials, you need a database management system such as Microsoft Access or MySQL.
Web Server Technologies
Many resources are available to help you learn more about the Web server technologies discussed in this presentation.
Many free magazines are available to IT professionals. These magazines can be a great source for learning about existing and emerging technologies, and choosing technologies on which you want to focus.
David Owens is a senior technical writer for Blackbaud, makers of software designed to help nonprofit organizations manage their fundraising, financial, and administrative operations. David strives to develop highly usable printed manuals, online information systems, and interface text for a wide variety of audiences, and to streamline methods of delivering content through single-sourcing. He has created user assistance for a range of products including a multi-module CRM application, a business intelligence solution, and utilities for network administrators. David gave a presentation based on this article at the 51st annual STC conference.