Web Design and Technology for Tech Writers

In today’s “digital age,” it is essential for a Tech Writer to have a working knowledge of web design concepts and emerging technologies.  This field, like many others, moved to the web about 10+ years ago when almost all other written content went electronic.  The entire field has radically changed in that time.  Everything has gone digital.  Yes, some companies still publish printed manuals, but most of the documentation is now digital and web-based. That’s why tech writing isn’t for everyone, because not only do you have to be a skilled writer, but you have to understand technology because you will be engaged with it on a daily basis. 

This comes relatively easy for me, because I grew up with technology as part of my everyday life.  I knew the importance of learning new technologies for success in today’s workplace and made sure to keep my skills current.  Most people fall in the early or late majority of the Technology Adoption Curve (below). Innovators are the people who wait in line to get the latest iphone, early adopters quickly buy and use the latest technology in their daily lives, the early majority is risk adverse and somewhat skeptical, they will wait for the next release when all the bugs are worked out or when the have read enough positive reviews, the late majority are the people who refuse to use a smart phone or use facebook, and the laggers are the people who refuse to own a home pc or a cell phone.  There is a chasm between the early adopters and the early majority where a lot of new technology falls.  Tech writers need to be early adopters to be on the cutting-edge of the field.

When most people start using a product for the first time, they generally just want a Quick Reference Guide or Quick Start Guide; just something that tells them the basics of how to get started.  No one wants to read a 200 page manual.  The most people will do is go through the online help, but only after they have run into a problem or are trying to do something that isn’t obvious.  So, writers have to find creative ways to make information stand out and be accessible to readers.   

For most products, the entirety of the user documentation is housed online.  Therefore, tech writers need to understand web design and how to author web-based materials.  There are many different help-authoring tools on the market right now that provide the writer with a relatively simple way of publishing online content (Flare by MadCap, RoboHelp and Framemaker by Adobe, and Doc-to-Help by ComponentOne for example).  Often HTML and CSS are necessary to style the output and make sure that it displays correctly on a number of different outputs.  For instance, some of these programs allow you to design output for internet browsing on PCs, iPads, and mobile devices.

In my role, at a software development company, my web design knowledge-base spans past authoring web-based documentation and help content.  I assist in the QA process, update the website, and create documents using the Adobe Creative Suite (InDesign, PhotoShop, Illustrator, etc).  All of these things require a working knowledge of web design, user interface design, and programming languages. 

I have developed a list of the basic concepts, skills, or programs that every tech writer should know.

  1. Be able to read and write in HTML, CSS, and XML.  Knowledge of  XHTML, Java, and Javascript is beneficial as well.  HTML (hypertext markup language) is the backbone of any webpage. CSS (cascading style sheets) is the style of the webpage; colors, borders – how it looks.  If you do not know these programming languages already, I highly recommend picking up any of the Head First books and using http://w3schools.com to learn.  That’s how I learned.  All the web designers I know are self-taught.  You can easily teach yourself how to do all of this without taking an expensive college course.  It’s not as daunting as it seems.  These books walk you through it step-by-step in a very simple, and easy to understand way.  They also have the “answer” on their website so you can see how it is supposed to look as you are developing. 
  2. Use Content Management Systems (CMS) (WordPress, Joomla, Drupal, Dreamweaver, or others).  Almost every website was built using a CMS because hand-coding is tedious and time consuming.  Besides, these systems do most of the work for you (who doesn’t love that?) because they have built-in designs and themes.  They have two different ways of letting you write, edit, and design the content, either in a visual pane – meaning that you can you can see the content as it would appear on the web and click on icons to insert hyperlinks, make headings, etc, or HTML pane – which has the entire web page displayed in code for manual editing.  You can toggle between the two different views, as I often do.  Knowing html and css can help you make adjustments to formatting that might not be available in the visual pane. 
  3. Use File Transfer Protocol (FTP) – Used for creating and maintaining web pages.  FTP such as WinSCP and Filezilla, (which are both open-source programs -meaning free, non-proprietary), allow you to transfer your web design files (HTML and CSS code files, image files, etc) to the web host.  You can easily move files back and forth across two panes (one for your computer and one for the web host).  You use FTP in conjunction with CMS.
  4. Know the different image formats and when to use them.  Images can be displayed in a number of different formats on the web.  The five most common are .JPG (or .JPEG), .GIF, .BMP, .TIFF, and .PNG.  .JPEG is best for photographs.  .GIF is best for line art, logos or other simple images without gradients or varying color.  .GIF can use transparency and animation.  .PNG does not support animation, but does support transparency.  It creates smoother graphics than .GIF.  .TIFF files are very large files but they produce a very high quality image.  .BMP files cannot be resized and are not compatable with all platforms. The ideal image file size is about 20KB.  Any larger than 1MB will take a very long time to load.
  5. Study User Interface (UI) design as well as Web Design.  Every program or system has a user interface – where the user interacts with the machine.  Learning design principles will help you understand the inter-workings of programs and will make you a better writer.  UI will also help you write readable online content.  Some of the design principles that I live by include: keeping the column widths around 75 characters, font no smaller than 12 point, and line height around 20px to 26px, and having paragraphs contain no more than 3-4 sentences with frequent subheadings. 

The list grows as technology changes, but knowing these basics will ensure that you are on the cutting-edge and capable of handling almost any project that comes your way.

Happy Holidays!

Even though I am very far away from home, and won’t be spending the holidays with my family, I am in good spirits because I will be with my husband, exploring our new surroundings and having winter adventures (ice skating, skiing even?).  This is our first Christmas as husband and wife, so it is fitting that we will be spending them together at home with our first (real) tree. 

It’s amazing how much my life has changed in the past year.  This time last year I was just graduating college and looking for a job.  I was wrapping up my internships, coursework, and submitting my thesis (whew!).  Now, I am living in Boston, a city in which I have always dreamed of living, working in a dream job, married to my best friend.  I even have my own intern now and have been asked to be a mentor for a Senior Seminar class that I was in last year by the professor who was my mentor a year ago.   It feels very different to be on the other side.  Sometimes it is difficult to see the positive things in life when you are faced with so many challenges, but the upcoming new year always makes me reflect on the one that just passed.  I am incredibly grateful for the amazing things that have happened to us, even though some days are very difficult.

I want to wish all of my readers a very Merry Christmas and a Happy New Year!  May your holiday season be filled with warmth and joy.

Lauren Hart

What is Technical Writing?

Every time I’m asked what I do for a living, and I respond with “I am a Technical Writer for a software development company,” I get blank stares and the follow-up question; “What is that?” I can understand how most people are unfamiliar with this field, because before I stumbled upon it in college, I had never heard of it either.  But if more people knew how often they interact with tech writing in their own lives, they would be surprised. 

An assembly manual for an ikea coffee table. An online how-to guide for using the latest iphone.  Clicking the “help” icon on any of their favorite desktop applications.  These documents were written by a technical writer.  The writer works with subject matter experts (SMEs) to learn the ins and outs of the item and/or process until they have become a SME themselves.  In many cases the writer needs to have prior knowledge and experience working in a specific industry.  

“Don’t tell me how it works, tell me how to use it.” – A customer.

The main skill of a tech writer is to translate highly technical, difficult-to-understand information into the most basic language possible (layman’s terms) using an economy of words.   Tech writing is not for everyone. It takes a very detail-oriented person who can learn and think on their feet.

“Easy reading is damn hard writing.” – Nathanial Hawthorne

In short, tech writers create, edit, design, and maintain documentation such as online help content, user manuals, instructions, grants, proposals, white papers, design specifications, flowcharts, process mapping, use cases, and other technical documents. 

Tech writers are often responsible for marketing, website development, recruitment, and social media networking. They work with computers and electronic publishing software (aka help authoring tools or HATs), including graphic design, page layout, and multimedia software on a daily basis.  

In software development, tech writers also perform quality assurance (QA) testing on software applications, provide graphic user interface (GUI) feedback on new development projects, act as an internal auditor for certifications.

These are just some of the main functions of my job.  The field is very diverse and can be open-ended in terms of the scope of each tech writer’s job.  I like it because it allows me to be creative and technical at the same time.  There is freedom to manage my own projects while working collaboratively with a team of developers.  If I want to learn more about web design, I can.  If I want to focus on writing grants and proposals, I can.  I am new to the software development niche, so I will be documenting my learning process throughout this blog.