Does a Technical Writer Need to Understand Web Design?
A reader asks,
Technical writing is a field that I've been pursuing and about to complete a certification. My question, how important or valuable would also pursuing a web design certificate for a technical writer?
The certificate in web design? Not necessary. But a working knowledge of HTML and CSS? Yes, critical, because everything is moving (or already moved about 10 years ago) to the web, including documentation. If you create help in a print environment only, chances are you still publish the PDF on a website somewhere.
About the only reason you wouldn't need to know anything about web design or development is if you're creating books in an attic. Don't get my wrong. Attics are pretty cool places, and if you have some musty old books up there, they might be fun to explore. But I doubt they would include software how-to books.
Why the Lack of Emphasis on Print?
After most users download a product, usually the only printed material they want is a short Getting Started guide. It gets them going with the product. As they start using the product and have questions, they search an online help site for answers.
Your online site is where the majority of your documentation should be available. Because of this, you need to understand how to author and design in a web environment.
Many help authoring tools allow you to get by with only a minimal understanding of web concepts. Others require extensive knowledge of CSS to style even the help's printed output. Whatever your situation, you should be familiar with basic web design concepts because your documentation will most likely be on the web.
In trying to distill the basics of web managing and publishing, I've come up with 10 basic concepts that every technical writer should know when working with the web.
Understand Basic HTML Markup
Understand how to type basic HTML markup, such as a heading, list, image, or link. You type an unordered list like this:
<ul>My list
<li>First item in a list</li>
<li>Second item in a list</li>
</ul>The code for an image is this:
<img src="https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/someimage.png" alt="my image name" />An image that links to something is just an image wrapped inside of a hyperlink.
<a href="http://someurl.com">
<img src="https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/someimage.png" alt="my image name" />
</a>Transfer Files with FTP
FTP stands for file transfer protocol. It's the way you transfer files to and from a web host. The most common open-source FTP program for Windows is Filezilla. To connect with FTP, you need a host address, user name, and password. Once connected, you usually see two panes: files on your local computer and files on your web host. You then move files from one side to the other to upload or download your files.
Modify CSS
CSS stands for cascading style sheets and is the language used to style almost everything on the web. You need to know CSS to design or modify a website, including changing the font or altering the headings or line height or layout widths. Almost nothing is coded in tables anymore (if it is, it's usually bad practice). Instead, CSS controls everything.
Most websites reference an external stylesheet where all the styles are defined. This page, for example, puts h1 tags around the post title. These h1 tags are defined in the stylesheet as follows:
.entry h1 {
border-bottom:1px solid #e6e6e6;
margin-bottom:20px;
padding-bottom: 20px;
}The first part, .entry h1, is called a selector. Selectors can consist of HTML elements, classes, or IDs. When you stack selectors together, you get a complex selector. In the above example, the complex selector refers to only h1 headings inside the .entry class. This style wouldn't affect all content tagged with the h1 selector.
For a good tutorial on CSS, see W3C Schools' CSS Tutorial.
Leverage CSS Tools
When you style a website, certain tools in your web browser can simplify the process considerably. Download Firefox, if don't already have it. Then download the Web Developer Extension and Firebug.
With these two extensions, you can quickly find and edit styles on a website. On the Web Developer extension toolbar, go to CSS > Edit CSS to edit the CSS for the page live. (You still have to save and upload your changes to make your edits stick.)
To identify the CSS selector for an element, right-click the element and select Inspect Element. (This option is available through the Firebug extension.) Now you can identify the CSS selector that is defining your site content, and then you can change the selector's properties in the stylesheet.
View Source Code
In Firefox or IE, you can also view the source code of the page you're viewing by right-clicking the page and selecting View Source. This shows you all the code behind the site. By viewing the source code, you can look for the styles around the elements that you're trying to adjust. You can also select a part of the web page only and choose to just view that selection. Once you know what CSS selectors are used, you can find and adjust the properties for the selectors in your stylesheet.
Create New Styles
You can create a new style with just a few keystrokes. For example, add the following to your stylesheet:
.mynewstyle {
font-size:30px;
margin-bottom:40px;
}</pre>
<p>Now on your web page, just add a div tag with that class before the text, like this:</p><div class="mynewstyle">
This is my sample content ....
</div>Now that text will appear in 30px font with a 40px bottom margin.
Knowing how to create a style like this can be incredibly helpful. You can use classes or IDs to create the styles. The same class can appear multiple times on the page, but you can only use the same ID once.
Use the Right Image Format
You should understand what image format to use. GIF and PNG support transparency, JPG does not. JPG is best for photos or images with gradients. GIF is better for solid colors. PNG works well for both, but the IE6 browser doesn't recognize transparency with PNG.
Whatever image format you're using, make sure the file size is small, such as 20KB or so. If your image is 1MB or more, it will take too long to load.
Make Online Content Readable
When you create content online, keep readability in mind. Column widths should be about 75 characters across. Font should be about 12 to 14 pixels. Line height (the space between lines) should be spacious, such as 20px to 26px. Additionally, you should chunk your content into small paragraphs consisting of no more than 3-4 sentences per paragraph, with frequent subheadings.
Subscribe to RSS Feeds
Most content on the web has an RSS feed. The RSS feed contains your content in a format that can be pushed out and parsed by RSS readers, such as Google Reader. Since people don't visit your site every day, you need a way to send them updated information on a regular basis. By subscribing to an RSS feed through an RSS reader such as Google Reader, you can follow hundreds of feeds without ever returning to the original sites to view the content.
Use Content Management Systems
Most websites are built on content management systems, such as WordPress, Joomla, Drupal, Expression Engine, or others. Hand-coding websites with individual, flat pages is a practice that's out of fashion given the ease and manageability that content management systems provide. Using a CMS to build your site is also a lot easier, since you can implement themes that have already been created by web designers. You can also leverage templates, reuse different design components, and take advantage of many plugins and extensions already created to increase your site's functionality.
Familiarity with these ten concepts won't make you a web designer, but it will allow you to get by with many of the tasks you may need to do with your documentation on the web.
----------
Photo by anvosa on flickr
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.