I'd Rather Be Writing » CSS

Does a Technical Writer Need to Understand Web Design?

Tom Johnson — Tue, 06 Jul 2010 14:24:52 +0000

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.

You don't need to understand web design/development if you're publishing books to a musty old attic.

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:

My list
	First item in a list
	Second item in a list

The code for an image is this:

An image that links to something is just an image wrapped inside of a hyperlink.

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;
            }

Now on your web page, just add a div tag with that class before the text, like this:


This is my sample content ....

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

Blog Sponsors

10 Challenging But Awesome CSS Techniques – Nettuts+

Tom Johnson — Tue, 31 Mar 2009 15:53:11 +0000

10 Challenging But Awesome CSS Techniques – Nettuts+.

Blog Sponsors

Styling Category Levels in WordPress (video)

Tom Johnson — Fri, 23 Jan 2009 12:25:38 +0000

Assigning unique styles to each category level in WordPress requires you to insert the following classes in your stylesheet:

Top level: .cat-item a { }
Second level: .cat-item ul li a { }
Third level: .cat-item ul ul li a { }

Styling Categories in WordPress

I created a five-minute video showing how the addition of these category classes to your WordPress stylesheet will change the style of each category level.

Watch the video

I also uploaded it to Vimeo, although the quality isn’t as good.

Blog Sponsors

YouTube – Introduction to CSS editing using Firebug

Tom Johnson — Thu, 22 Jan 2009 14:35:44 +0000

Introduction to CSS editing using Firebug (youtube)

If you work with CSS at all, Firebug is essential.

Blog Sponsors

Coding Horror: The Two Types of Browser Zoom

Tom Johnson — Thu, 22 Jan 2009 12:00:50 +0000

Coding Horror: The Two Types of Browser Zoom.

For help authors producing browser-based formats, the issues in this post may impact the usability of your help. How will Zoom impact your design?

Blog Sponsors

How to Create Columns with CSS Float | eHow.com

Tom Johnson — Thu, 01 Jan 2009 06:49:34 +0000

How to Create Columns with CSS Float | eHow.com

I see so many sites that structure everything with tables. News flash: tables are out. Divs and floats are in.

Blog Sponsors

Conditional-CSS

Tom Johnson — Mon, 11 Aug 2008 15:25:32 +0000

Conditional-CSS.

Approaching Help as Solutions to Problems — An Interesting Format from the CSS Cookbook

Tom Johnson — Wed, 02 Jul 2008 01:27:17 +0000

At Borders or Barnes & Noble, I often browse the computer books to see the different ways writers approach help material — especially how they approach the same help material.

The other day I wanted a book on CSS, so I pulled four available CSS books off the shelf and began browsing them. Each book looked respectable, but the CSS Cookbook, by Christopher Schmitt, had a unique format that caught my attention and convinced me to buy it.

In the CSS Cookbook, each topic is formatted with Problem and Solution subheadings. Here’s an example:

I like the problem-solution format. For one, while sitting there trying to choose the right CSS book, the problem-solution format convinced me that the book would deal with my actual problems, not just provide general CSS rules and principles. That feeling — an extremely compelling one — won me over to the help.

Almost invariably, the reason we turn to help is to solve a problem. Some would say every human action is driven by the desire to solve a problem (People don’t go to Home Depot to buy a shovel; they go to to dig a hole, as someone once said). But it’s especially true for help material. Problems are the explicit motivation for why we turn to help. Consequently, help material that arranges itself around problems and solutions isn’t too far-fetched of a format.

At the Trends Panel at the last STC Summit, the panelists even recommended that technical writers become problem solvers. Write less and think more, they said. You don’t write — you solve problems. As you solve problems, your value in the organization increases. They essentially recast our role from writer to problem-solver.

Perhaps it would change the way we wrote documentation if we looked at help as a collection of problems and solutions rather than features and functions. Rather than asking, What can a person do on this page of the application? instead ask, What problems might my user have here?

At the very least, thinking in terms of problems would perhaps get us out of the vocabulary of the application and into the vocabulary of the user. For example, rather than addressing how to “create navigation menus,” we would be writing about building a “curved tab navigation menu that works even when text is resized” (as one problem in the CSS Cookbook is worded). The first is a general help topic; the second is phrased more after the language of users.

Some readers may object and say that we’re already thinking of problems and solutions unconsciously when we write help. In part, sure. But adopting an explicit problem-solution paradigm would make us even more in tune with the actual problems users encounter. Rather than focusing on the general topics, it would help us focus on the scenarios where users will be challenged and confused.

The problem-solution format has its share of difficulties. The main difficulty is that some topics have problems, and others don’t. A problem, in my mind, is one with specific circumstances and variables. A hairy situation. Here’s an example where the problem-solution format feels forced.

In this example, the problem is so simple it doesn’t feel like a true “problem.” And the problem merely repeats the title, so it seems redundant. The repetition isn’t needed, but for consistency’s sake, the author carries the problem-solution format into every topic.

Another difficulty is crafting the topic title. At times the title succinctly states the problem; at other times the title strays from the problem. If the title just repeats the problem, the problem seems redundant. If the title is too different from the problem, the title seems poorly chosen.

In these situations, the saving grace is the Discussion section, which I haven’t yet mentioned. After the Problem and Solution sections, the topic usually has a Discussion section that brings up other related points surrounding the problem. When a topic has a discussion that touches on several related issues or considerations, the repetition at the beginning is forgiveable. In that situation, the Problem section merely provides a concrete starting point for a larger discussion.

Overall, the problem-solution format probably works best for more advanced help, where the solutions are more complicated and involve combining several general principles or bending traditional rules. Despite the challenges I mentioned, in looking over the book, the format appeals to me more and more.