What I Learned from Software Developers
Contents
Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.
Introduction 
Technical communicators who work in documentation departments develop work habits based on their fellow writers and editors. As a lone writer, my group members are software developers instead. If you have only dealt with software developers as subject matter experts, you probably have not had a chance to observe their work habits closely, nor hear their opinions about best practices. Being a member of their group has afforded me this opportunity, and it has taught me about many different tools and techniques that make me a more efficient and productive technical communicator. I would like to share some of those lessons with you.
The following sections describe different tools and methods that I have adopted from software developers.
Use a Version Control System
A version control system keeps track of each draft of your document when you check it into a repository. It records who checked in the file and allows you to store other metadata (information about the information) about the file. You can easily retrieve and (depending on the file type) compare previous versions. You can be notified by email when a file is changed by anyone, and it prevents you from checking in a file if you did not start with the latest version. It has a configuration control feature where you can tag the files to identify them as the versions that comprise a particular release of a product.
This is a common application used by software developers. There are many types to choose from, such as CVS (Concurrent Versions System), Subversion, IBM® Rational® ClearCase® or Microsoft® Visual SourceSafe®. Some are even open source (which means that they are free). If your employer has software developers, chances are that they already have a version control system, and you can simply join them in using it.
It might not be ideal for documentation; for example, if your documentation files are binary, the system may have to store the entire file when you make a change instead of storing just the change. However, it provides far better control than storing files on a server or your hard drive.
Document Everything You Do and How You Do It
Software developers are trained to put comments in their code. Perhaps that is why they are more conscientious about documenting everything they do.
Documenting everything you do and how you do it is not only useful to the next person who has to do the same thing (whether they are your co-worker or your successor), it's useful to you. The next time you have to do the same task or remember why you did it that way last time, you will thank yourself for taking the time to document it.
Much of our internal documentation is done on a wiki that everyone in the office can access. A wiki offers an easy interface to provide input, search and access information. It also allows collaborative work in an environment with enough controls (changes are recorded so that you can identify who made the change and roll back the change if necessary) to make the contents trustworthy.
Look for Answers on the Internet
Are the SMEs using strange language and odd abbreviations? Are they spelling the same term several different ways? Do you get error messages when running some popular software? Is your publishing system causing you headaches?
Software developers often find solutions by doing an internet search, consulting some of their favourite reference sites, or participating in forums and discussion lists. You can do this, too, although you will probably choose different reference sites and forums from them.
Yes, even an error message can be found on the internet. If it's from a commonly used application, chances are that someone else got that error too, and asked about it on a forum. Most likely, a helpful person answered their question on the same forum, where you can get the answer.
Some of my favourite reference sites are:
Alternative Tools
Software developers are always looking for something faster, better-designed, less buggy, or free. Given a chance, they won't stick to the company standard. Because of software developers, I have started using the following tools.
Google Chrome
Internet Explorer or Mozilla Firefox are the typical company standards for web browsing, but several of my colleagues have changed their default browser to Chrome. It loads pages faster, and has some convenient features: searching in the address field, and opening a new window by dragging and dropping a tab. You can read plenty of articles about why Chrome is better than the others [1] [2]. However, I wouldn't have considered it if my colleagues weren't using it and giving it good reviews.
Beyond Compare
This tool compares two or more text files side-by-side and allows you to transfer differences from one file to another. Recent versions also compare PDF files. I frequently use it to pinpoint what changed from one version to the next in a file.
Vim
This is the PC version of the infamous UNIX editor called vi. Vim is more user friendly than vi, but still retains most of the powerful editing features. If you have to work in a text file such as XML, some programming code, or a batch file, vim will highlight the key words for you, provide text completion, and even do some basic syntax checking. One of its best features for a technical communicator is its ability to use regular expressions for search and replace activities which takes global changes to a whole new level. (A regular expression is a set of pattern matching rules encoded in a string according to certain syntax rules.)
Automating Tasks
Anything can be easy to do the first time, but by the tenth time, it gets boring and error-prone. Software developers hate doing repetitive tasks. They would much rather write a script [3] or buy something to automate the job.
While technical communicators are usually fond of graphical user interfaces (GUIs), that kind of interaction does not automate easily. Software developers are always interested in application programming interfaces (APIs) so that they can write a script to automate the task. You might want to check for this feature the next time you invest in a software tool.
Once the script is written, the task is accomplished in less time, more accurately, and more reliably.
Many scripting languages are available and widely used, such as Perl, Tcl/Tk (pronounced "tickle tee kay"), and Python. If you work with software developers, they probably know at least one scripting language. If you don't know one and don't have time to learn, you might be able to ask them for a favour. They can often whip up a script for you in less than an hour, and it will save you many hours of work in the long run.
Work in a Text File Instead of a GUI
Software developers love text files. Maybe it's a result of working with so much programming code. I gradually came to realize that text files have some advantages over WYSIWYG interfaces:
- They lend themselves better to automated tasks.
- They are more accessible and transferable because you don't have to purchase a specific program to open them.
- If you have to configure something, a text file is easier to copy and modify than a configuration created with a GUI.
- It is much easier to compare two versions of a text file than binary file formats.
I still prefer to work with a GUI; for example, tables are much easier to create and manage in Word or FrameMaker than in text files that use mark-up, such as HTML or a wiki page. But sometimes, converting the contents to a text file is a more efficient option.
Use a Software Development Methodology
By software development methodology, I'm referring to the process of writing down the requirements and the design, doing the development work, and having regular reviews along the way to ensure that the end product meets the requirements (i.e., testing or verification). [4]
For technical communication projects, I'm suggesting an abbreviated version of the planning documents to suit the size and complexity of the project. A brief description of the requirements and design can help to control project creep, and clearly define the end of your project. Otherwise, you'll end up adding refinements and new features as new ideas come up. The planning documents can be as short as an email; just make sure you can find them again when you need them.
It also helps to have the requirements and design reviewed before you start the development work. Just like an outline ensures that you haven't missed an important idea, these planning documents make sure you are on the right track. They are worth the time and effort compared to restarting the development work.
I usually use the templates designed for a software project and adapt them to my needs (mostly by leaving out a lot of things), but if you'd like a template that is designed for documentation, you can contact Neil Perlin of Hyper/Word Services (nperlin@nperlin.cnc.net). I obtained an online documentation specification template from him when I attended one of his workshops.
Consider the Maintenance
Software developers know well that most of the resources on a project are not spent on creating it in the first place, but maintaining it. Therefore, their philosophy is to make the maintenance as easy as possible.
Technical communicators should be thinking the same way. It's easy to add a lot of detail and screen captures to a manual, but what happens when the user interface changes? And can you find all the places that are affected by the change?
We are usually so concerned with providing useful information to our readers that we often don't consider how to maintain that information when the product changes. If we can't keep up with the changes, our readers still suffer with inaccurate, inconsistent, or late information in the next release. The trick is to find the balance between providing enough information and keeping it maintainable at the same time.
Naming Conventions
As every good software developer knows, file names are important. A consistent and well-considered naming convention can:
- Help you and others find the item that they want
- Make scripting or batch files easier to use on the set of items
The items might be document files and folders, a collection of graphics, or documents on a wiki. If your system of items is sufficiently large or likely to grow, you will avoid frustration later if you can establish a naming convention near the beginning of the system's development, and then stick to it.
Conclusion
The application of these tips depends on your working environment, resources, and personal preferences. In any case, I hope that you will consider examining the practices of other professionals in your area to see what can be applied to your own job to improve your job satisfaction.
References
- Ulanoff, Lance (February 2, 2010). Why Chrome Will be Your Next Browser. PC Magazine. Retrieved from http://www.pcmag.com/article2/0,2817,2358686,00.asp
- Pash, Adam (September 22, 2010). How and Why Chrome is Overtaking Firefox Among Power Users. CY.TALK. Retrieved from http://internet.cytalk.com/2010/09/how-and-why-chrome-is-overtaking-firefox-among-power-users/
- Morin, Rich & Brown, Vicki (1999). Scripting Languages: A Cross-OS Perspective. MacTech, Volume 15, Issue 9. Retrieved from http://www.mactech.com/articles/mactech/Vol.15/15.09/ScriptingLanguages/index.html
- Östen Oskarsson Systemkonsult independent consultants. Procedures for Software Development: In Management of software in development and procurement. Retrieved from http://www.oskarsson.se/useful_info/handbook.html
Fei Min Lorente has been a technical writer for over 20 years in the software, hardware and defense industries. She has savored the challenges of new technology, including pioneering the production of Eclipse Help at ON Semiconductor. She has extensive public speaking experience teaching internal company workshops and lunch-time learning sessions, as well as presenting at the local STC chapter, the international STC conference, the FrameMaker Chautauqua and WritersUA conference. She is currently the President of the Southwestern Ontario chapter of the STC, and she considers herself a programming dilettante.
Fei Min Lorente
Senior Technical Communicator
ON Semiconductor
feimin.lorente@onsemi.com
