I'd Rather Be Writing » Web Design

Arguments for and Against Tripane Help

Tom Johnson — Thu, 17 Mar 2011 14:27:43 +0000

My colleague Ben Minson wrote a post about why tripane help is a relic of the book-paradigm documentation age, and how it can limit us from taking advantage of other web technologies. See Why I Don’t Like Tri-pane Help.

As a quick definition, tripane help is the standard webhelp HTML output that has several frames — the table of contents pane on the left, the main topic area in the middle, and a pane across the top. For example, here’s a sample tripane help I created a couple of years ago for WordPress:

This is an example of tripane help. It's all a giant frameset, with the table of contents on the left, a navigation bar across the top, and content in the middle. That's three panes -- hence the name, tripane help.

I agree with Ben’s arguments that discourage tripane help, and yesterday I even wrote somewhat of draft rant titled “Rest in Peace, Tripane Help.” But as it was still in draft mode, I mulled it over. I also listened to a Scriptorium webinar on DITA Best Practices by Tony Self, which helped me see another side of the argument. In this post, I want to present a more balanced argument for and against tripane help.

Cons of Tripane Help

Let’s start with the cons of tripane help.

Hard to modify. Have you ever tried to modify the look, feel, or functionality of tripane help? It’s usually a complicated undergrowth of impenetrable frames and custom code. Hacking RoboHelp’s webhelp, for example, requires you to dive into arcane tips and tricks from sites such as Rick Stone’s RoboWizard, which still looks, with its outer space background, like websites did back in 1995. Rick’s site itself is an example of tripane help.

Rest in Peace, Tripane Help

Flare gives you finite control over the style of each element, but not over the larger structural elements. What if I don’t want frames? What if I want the main search engine on the home page? What if I want the sidebar on the right, with drop-down submenus that slide out? Why can’t I just code it with a separate CSS file from scratch like a regular website, choosing what I float, choosing the behavior of my navigation buttons, etc?

Overall, tripane help is hard to modify because of the extensive frameset and proprietary code.

Looks outdated. Although you can tweak its styles here and there, you can’t make tripane help look like a regular website. It just doesn’t fit in with anything on the web that you find post-2005.

The more we move into the future of the web, the greater the divide grows between tech comm and interaction design. That divide worries me. When people see a tripane help site open up, it immediately signals a sense of outdatedness.

Lacks web functionality. It’s not just about the limitations of tripane help’s look and feel, though. It’s also about web functionality: RSS feeds, comments, embedded videos, lightboxes, jQuery effects, real-time editing, browser-based authoring, built-in metrics, category links, tags and tag clouds, most popular articles, faceted browsing, instant search, search engine optimization, threaded conversations, and so on. You don’t get hardly any of this with tripane help. Ouch.

By confining our HTML deliverable to the rigid tripane help, we become distanced from the forward movement of the web. We become publishers of HTML content but without any of the slick knowledge of web design or interaction design.

Keeps you in book paradigm mode. As Ben points out, we also get stuck in a book paradigm mode, where the only idea we can come up with for organizing our help content is a bunch of topic folders. Ben points out:

One of the limitations of a TOC is that you can display only topic titles. If you set up pathway pages like Redish describes, you can give the reader more guidance. A risk you take with TOCs is that as the user doesn’t find what he wants, he expands more and more books or folders, and he ends up with an overwhelming list of topics. Instead of holding his hand and leading him along, you’ve paralyzed and frustrated him.

In my experience, help authoring tools don’t lend themselves to dynamic Web outputs that allow you set up this kind of guided experience. You could do it, but it’s not supported well out of the box.

Limits your technical creativity. When we get comfortable with a tool that allows us to publish tripane help, we get locked into whatever built-in features and capabilities the help authoring tool allows. Sometimes we can hack in tweaks and other modifications, but it’s usually not worth the hassle. What happens when we want to try leveraging some of the more web-like features to improve our help, such as faceted browsing or instant search? Because we have confined our technical prowess to a specific tool, we’re not equipped to be more creative and innovative with new approaches to help. We become dependent on tool vendors for innovation.

Pros of Tripane Help

Now for the pros of tripane help.

A tripane help output can help us separate content from design. You're free from worrying about matters outside of content. In this sense, tripane help can be liberating. It breaks the chains that hold you back from focusing more on content.

Allows you to focus on content. In the Tony Self DITA webinar, Self stresses that the paradigm of DITA authoring is to separate content from format and design.

In the DITA model, an author creates a standalone topic that is independent of any particular book or format. This standalone topic can be pushed out into any deliverable or any table of contents and stand on its own. Because of this, the DITA writer doesn’t worry about styles or design. The DITA writer can focus on the content, because after all, this is what ultimately matters.

Tripane help allows you to avoid worrying about format and design. You don’t have to consider the details of the CSS and the look and feel of the content in the web output. Someone has already taken care of that. The design has already been created, and you can redirect this effort that you would normally spend on design and apply it to your actual help content (perhaps creating illustrations and other content diagrams, if you still have an itch to design something).

Most users don’t complain about the design of help anyway. They complain about the poor content, right? So doesn’t it make sense to focus on content rather than design?

Allows variety of classification schemes. At first, it seems that you can only create a topic-based hierarchy for your table of contents (TOC) in a tripane help. The tripane help seems to force you into a book paradigm. But this is only convention. You could abandon the traditional TOC approach and instead organize the content by audience, by timeline, by most popular support requests, or some other scheme.

A lot of tools that produce tripane help have tagging, relationship tables, and other techniques for applying non-traditional organizations. In fact, these tools may even make it easier to manipulate the content in alternative ways.

With the robust TOC that tripane help offers, you could build these alternative entry points directly into the TOC, giving users several different ways to navigate the content — by task, by role, by workflow, by popularity, by department, by feature release dates, and so on. Tripane help gives you an easy way to do this, rather than relying on a web team or a JavaScript/interactive designer to help you code these features.

Provides content re-use, localization, single sourcing. Although these benefits aren’t specific to tripane help, using a tool that auto-compiles to a tripane help output usually gives you additional advantages with content re-use, localization, and single sourcing. You can conditionalize content for various role-based, versioned, or beginner/advanced types of guides. You can package all your files up and send them off for translation, and then reimport them. You can single source your content into print and online and mobile deliverables.

Sure, a web 2.0 site looks cooler, but is it worth the sacrifice of content re-use, localization, and single sourcing, which may be much more important for technical documentation needs? All of these additional benefits are usually available if you stick with tripane help instead of abandoning it for a web-based content management system.

Conclusion

One of the potential fixes for the tripane help eyesore, without losing the benefits, is to have the help authoring tool output its content into div tags that you can use to structure and style as you wish. If you can escape the traditional tripane look and generate a more attractive website, you can move towards the best of both worlds.

Unfortunately, tripane help has helped contribute to a growing divide between interaction designers and technical writers. So even if you could structure your output with div tags, most technical writers lack these web design skills. They’ve been limping along with the tripane output for so long that even basic HTML is often an unexplored territory.

Additionally, most technical writers aren’t familiar with any other information architecture techniques outside of basic topic-based hierarchies, so they may not feel a need to innovate with alternative organization patterns.

Blog Sponsors

Trends in Search Engine Optimization — Shifting from Search to Social?

Tom Johnson — Tue, 01 Mar 2011 03:35:13 +0000

In The Big Shift from Search to Social, Anne Gentle notes the growing problem with Google’s search and trends towards alternative search sources, such as social networks like Facebook. She links to an stirring NY Times article called The Dirty Little Secrets of Search, which I recommend reading.

The Dirty Little Secrets About Search, from the NYTimes

The NYTimes article exposes how search engines are gamed, and how search engines can also game consumers.

As the NYTimes article points out, the strategies for gaming search engines often involve buying links pointing to your site. I’ve encountered a bit of this myself. Last week a “reader” offered to write a “guest post” for me on Wikipedia’s credibility issue, and how Wikipedia manages this risk. The guest poster only requested that in exchange for the completely unique post, he be allowed to include a “personal link.” When I received the post, it turned out to contain a link to an online university site. I turned the article down, not only because it wasn’t relevant to my blog, but because I get at least one person a month pitching a guest post with a link to an online university.

I’ve had offers from other companies to run text ads in my blog. Several years ago I made about $1300 just adding text links to website companies on about 20 old posts. Recently the same person returned to pitch more text ads to an exam-answers site, which I turned down for obvious ethical reasons. But regardless of the site, running text ads isn’t a good practice — if Google finds out, they could penalize your Pagerank.

Pagerank is always a bit of a mystery, but ever since MindTouch came out with their 20 most influential bloggers, and showed Scott Abel’s The Content Wrangler with a Pagerank of 7, and my site with a Pagerank of 5, I started to worry about the effect of those text ads. I removed them (I think they expired anyway), and after several months my site’s Pagerank is now a 6. Part of Scott’s Pagerank is due to the longevity of his site, I believe. He’s been online probably longer than most any other technical communicator. Also, he does post excellent, in-depth content — rich with search engine keywords.

Although Anne notes that Facebook visits surpassed Google visits, I’m not sure if this is an apples versus oranges argument. Are people turning to Facebook and other social networks primarily to find information, or for social engagement? I occasionally search for keywords on search.twitter.com, especially if I’m looking for something occurring now. But as a general means of finding information, I almost never search social networks.

However, when I can’t find information, perhaps because the search engines are gamed with all kinds of J.C. Penney type schemes, then yes, turning to social networks is a good idea. For example, last Friday I googled how to create a screencast of an iPhone app, and not finding anything on Google, I turned to Twitter. But other than turning to social networks as a last resort, for me social networks primarily serve social purposes, and search engines primarily serve search purposes.

What does this all mean for technical writers? We keep hearing that technical writers have a goldmine of SEO-rich content, and that companies need to leverage the search engine results and financial benefits that will come from putting this content online in the realm of user search. SEO and web platforms should play a larger consideration in how we author help material — particularly if our audience is external. It’s usually more than enough, though, just worrying about accuracy, concision, and content approval. Now if you add good SEO practices to the mix, you have a lot going on in each topic.

Blog Sponsors

I am perhaps finishing my basement, someday

Tom Johnson — Wed, 23 Feb 2011 14:39:20 +0000

My wife wants to finish our basement so badly that she registered for a local eight-week course on how to finish your basement. As the first class approached, she realized how difficult it would be for me to nurse the baby while she learned about framing, plumbing, electricity, and so forth. So I agreed to go instead.

I had been putting off finishing my basement for a long time — two years now — because it’s costly and I never seem to have the time. Additionally, I’m not a handyman so I really have no idea what I’m doing.

After attending the first class, I was so excited to throw myself headlong into the project, I immediately bought a framing gun and compressor. The store clerk explained how to put on the couplings. I also bought more than $300 worth of framing lumber and neatly stacked it into my basement.

The instructor explained that I could google or youtube any topic and find abundant instruction online. He was right. We live in an era of complete do-it-yourselfism. If you search youtube for videos on how to frame your basement, you could watch them endlessly.

The week after the first basement class, I spent a good amount of time clearing out all the junk from my basement. You need a clean working space to build. I also drew the blueprints of what I plan to build. Other than once replacing a radiator in my car, this is the largest project I’ve ever tackled.

The basement diagram I drew as I prepared to finish my basement.

Monday I took President’s day off and planned to do the framing, but I realized I don’t understand the process well enough. Does the vapor barrier go on the inside or outside of the insulation? Should I use polystyrene foam? What about those hairline cracks in my walls that have water stains around them? Is that something to worry about, even though I dug out the window wells and pretty much fixed the water penetration problem? Do I need to do a moisture test with a piece of plastic covering those cracks for a couple of days? What are the actual city codes for vapor barriers? Should I remove the existing insulation, which only covers half the wall? Why would it only cover half the wall? Newer homes have the insulation covering the entire wall, so have the city codes changed, and am I now responsible for the new codes? Does the vapor barrier have to be continuous, or can I tape an addition to the existing half wall?

One problem with do-it-yourselfism is that there are so many youtube videos online, they present conflicting methods and advice. Read enough of it and it can become paralyzing. Although sometimes I follow an impulsive behavior and try to learn from doing even as I screw up, I realize that unless I do this right, I could end up redoing everything, or getting mold, or not passing code. I could spend weeks learning this stuff. For a one-time job, it hardly seems worth it.

I am being very cautious, but sometimes my behavior gets neurotic. For example, when I initially ordered the framing lumber, at least a third of it had little mildewy spots. I googled mildew/mold on framing lumber, and I ended up taking it all back to the lumber yard and hand-picking every piece of wood. The lumber yard man said, You’re not building a piano with this stuff. I took my time picking through the lumber yard piles.

I would much rather bury my nose in WordPress projects or something computer-related, but honestly, there’s a lot I don’t know about WordPress too. Try building a theme from scratch or a plugin — there’s quite a bit to it. You can quickly run up against the same intimidating wall of how-to.

My mother-in-law feels strongly that I should finish the basement myself, in part because she’s very handy at this stuff herself (she once cut her own skylights on a whim). But the question of whether to finish a basement oneself or to hire out feeds into a larger issue of buy versus build, specialist versus generalist, one role versus multiple roles?

Do-it-yourself is everywhere, because information is everywhere. But everything is also more specialized and technical. It does make sense many times to do it yourself by studying it out through the scattered information you find online, but although the information is available, the tasks are also often more technical, more specialized, more expert, and more involved. For example, you can find information on how to change your headlamp bulb on a 2003 Nissan Altima. The only problem is that you have to take off your entire front bumper to do it.

I tend to lean towards the “do one thing really well” philosophy, since it’s usually more rewarding to be an expert than to be someone who is always struggling to understand. But sometimes you have to develop multiple skills because you can’t get anyone else to do it for you. For example, I spent about two days drawing the following illustrations to liven up a page of text in a help file.

My foray into Illustrator

I bet a graphic designer could have done all this in one afternoon. But alas, I do not have a graphic designer sitting next to me with a billing code and spare time. And similarly, I do not have $25k to finish my basement.

Blog Sponsors

WordPress Tip: Integrating a WordPress Blog into your Website

Tom Johnson — Thu, 09 Dec 2010 07:48:11 +0000

Integrating a WordPress blog into your website is one of the most common requests I receive as a WordPress consultant. Whenever someone asks me to do this, I usually recommend moving the entire website into WordPress. That way you can manage all the content in one place. The user experience is more seamless too.

If you’re interested in having me convert your website into a WordPress-driven site, contact me.

Here’s a 5 minute screencast showing a project I recently worked on. In this example, we converted an existing static website to a WordPress-driven site (grandriverhospitaldistrict.org).

http://www.youtube.com/watch?v=T3tt4J_5uss

Blog Sponsors

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

Designing from the Content/Story Out

Tom Johnson — Mon, 28 Jun 2010 06:47:30 +0000

My wife Jane attended a Segullah writer’s retreat conference this weekend. During the conference, one of the presenters explained a common mistake many novice writers make: they look for stories to fit a pre-selected theme.

You hear the result of this strategy most commonly in church talks. Someone is assigned a topic, or has a topic he or she wants to explore. To make the talk/presentation/essay appealing, he or she looks for stories to fit the theme. The result is that each story is moralistic, simplified, and often distorted to fit the speaker’s purpose.

A better approach is to start from the story and see what theme it moves towards. In other words, follow the story to whatever theme/meaning it naturally leads you to, rather than trying to fit it into a pre-selected theme. Even if you want to take one path (in the photo below, for example, Mandan Cottages), if the story naturally pushes you toward another path (for example, Return to Sundance), go with the natural path of the story.

It’s excellent advice, but not just for writers. The advice is a cousin to the commonly heard UX principle of “designing from content outward.” It’s the same idea that people who wear shirts with a big red x through the words “Lorem Ipsum” are trying to get across. Start with the content first and then create a design for it. Otherwise your design won’t fit the content.

In a writeup on the SXSW 2010 conference, Adam Schwabe explains the importance of starting with content first. He says,

Content is all too often considered as an afterthought after wireframes and design comps have been presented to and approved by the client. Relegated to boxes as placeholders and Lorem Ipsum, too many of us take a “do it later” approach with what is most important to the user. People aren’t visiting your site to look at colours and boxes, they’re there for a purpose, and the content should be at the core of any design. (SXSW 2010: Trends and Highlights)

Just as writers start from story and build meaning from those events, user experience professionals start with content and design the frame/layout for it. It seems obvious, but few follow this logic.

If you create a design that doesn’t stem from the content, you end up with a mismatch. When it comes to add your content, you find that your content/story doesn’t actually fit the design/theme.

Blog Sponsors

Embedded Links and Online Reading Accessibility: Whitney Quesenbery and Caroline Jarrett, #stc10

Tom Johnson — Fri, 07 May 2010 13:37:46 +0000

In this video, I talk with Whitney Quesenbery and Caroline Jarrett about the feasibility of removing links embedded directly within paragraphs — which Kathryn Summers and Ginny Redish describe as “exit points” that confuse and disorient low-literacy readers.

Blog Sponsors

What Would a WordPress Template for Chapter Sites Look Like?

Tom Johnson — Tue, 02 Feb 2010 14:00:08 +0000

Last week Will Sansbury mentioned to me that one of his ideas with the Atlanta chapter site was to provide an example or template of how WordPress could be used for chapter sites. I got to thinking, why isn’t there a standard WordPress template for chapters and SIGs to use?

Further, in WordPress 3.0, WordPress MU and regular WordPress will be merged. This is huge, because it means you’ll be able to create child blogs with a regular WordPress install. Essentially we could have one site like stcchapter.org with dozens of child blogs, containing subdomains such as intermountain.stcchapter.org, wyoming.stcchapter.org, and so forth.

For those chapters that just wanted a simple web solution, they could create a child blog from this site. They could also point their regular domain to the site. The themes and plugins available in child blogs are dependent on what the parent blog chooses to provide.

I think the idea of providing a site template from WordPress is ingenious. It made me think about exactly what a chapter WordPress template would look like. I wish I could say our Intermountain-STC site is a perfect example, but it’s not (not yet anyway). I spent a good chunk of time this weekend tweaking a few things. Here are several elements that I think a chapter WordPress template would have.

Subpage Lists

To accommodate this simplicity, the sidebars for each of the pages should show all the subpages for the current page. And here the amount of content in the sidebar can be as abundant as you want, from three page links to thirty or more. The submenu page list hides the complexity. (Fortunately, showing a list of subpages for the current page is simple with the LJ Subpages Widget plugin.)

Subpages appear on right for the selected page, allowing you to hide the complexity of information up front and only show the information when a user is on the relevant page

Custom Sidebars

Implementing custom sidebars feature takes the concept of the subpage lists to another level. Each main page should not only show the subpage list for the current page but also have an entirely unique sidebar showing content specific to that page.

Why? Two reasons. If you have the same sidebar content for each page, the reader’s eye becomes blind to it. So even if you have the changing subpage list at the top, the reader may not notice the changing links if the rest of the sidebar remains the same. But if the entire sidebar changes for each of the seven or eight main pages, that’s something you notice. The reader can anticipate that the sidebar content will contain unique content for the specific page he or she is viewing.

The sidebars are unique for each page the user is on. For example, with the Jobs page, the user can see information on subscribing to job email alerts and a jobs RSS feed.

Second, having a custom sidebar for your page gives you more room to present information for that page in an attractive format. You can give more information to the reader above the fold, without having to scroll.

Author Pages

Above all else, a chapter site should be collaborative. Multiple chapter members should be able to access it, author content, and publish. You want to highlight and promote the collaborative nature of the site. Posts usually contain a byline, and the byline is a hyperlink to the author’s name that shows the author’s bio and posts. The default author template called is the author.php page, so you can customize this page to show the author’s picture and bio information at the top, like this:

Author pages show contact information, profile text, and posts published by the author

You can also show a list of authors in your sidebar (see the lower-right section of the image above).

Special Widget Sections

One of the cool things about WordPress is the drag-and-drop widget feature. You drag the widgets you want into the sections on the right. Most people don’t realize that you can create additional sections for your widgets that map to different areas of your templates. For example, you can create 10 or more special sections that correspond with the different pages. This way the people who maintain the site can configure the sidebars without even touching the code.

In the following screenshot, you can see that I’ve created a new sidebar section for each of my main pages. You can now drag whatever widgets you want into each of those sections, depending on what you want in the sidebar for that page. This is one way you transform WordPress into a CMS.

You can create new sections for your widgets

Custom Homepage

Rather than showing About information or a list of the latest posts, I think the home page best serves its purpose by showing the next chapter meeting, the latest jobs added to the site, the latest blog posts, and general news. The home page of a chapter site should give you a summary of all the important information you may need to know.

The home page shows a summary of the most important information

These are just my initial thoughts about what a chapter WordPress template might include. I’m currently trying to convert the Intermountain-STC.org site into exactly this template. Any thoughts on what else a chapter or SIG site would need?

Blog Sponsors

Fragmented Communities and the Chapter/SIG Web Site Problem

Tom Johnson — Mon, 01 Feb 2010 15:33:18 +0000

Recently Will Sansbury and I gave a webinar to STC community leaders on chapter and SIG websites. Rather than giving a static, one-way presentation about theoretical concepts with web design, or boring people with technical details they probably didn’t care about, we held the webinar more like a design review workshop, not too different from a writing group workshop.

Although I spent three years in a creative writing program holding exactly these types of writing workshops, in which a group of people provide feedback on the story or essay someone submits, it never crossed my mind that designers probably sit around tables doing the exact same thing with websites.

Design Reviews

Regardless of the topic, the methodology of the workshop is mostly the same. In a tactful way, you explain what works well and what could be improved. Others either agree or disagree with your analysis, and hopefully they explain why. The only difference between critiquing creative stories and websites is in the questions you ask. Rather than ask, what’s the story here? Are the characters believable? Does it have arc? You ask questions about findability, simplicity, readability, and so forth.

I found that in looking at websites, my feedback could be grouped into about seven categories:

Purpose

What are you trying to achieve with the site?
What do you want the audience to do on the site?
What do you want feedback about?

Findability

What are some things your users might be looking for? Is it easy to find them?
If you search for something, are the results accurate?

Simplicity

Is the site navigation simple to understand?
How does the site handle submenus to provide additional information?
Is the site busy?
Is there enough white space in the site?

Readability

How easy is it to read the content?
Is the font size, column width, leading, and typography working together in a readable way?
Can I subscribe to the content with Facebook, Twitter, RSS, or e-mail to read it in the format I want?
Are the paragraphs small, broken up with lists, blockquotes, and other formatting varieties?

Interactivity

Can I add comments on things I read?
Can I read other people’s comments and reply to their comments in a threaded way?
Can I contact someone through an email address or contact form? If a contact form, do I know where it goes or if it sent correctly?
If I have a job to post, can I submit the details myself? Can I even post it myself?

Content Appeal

Is the content interesting to read?
Is the content current?
Can multiple people author and maintain content, so that all the burden isn’t placed on one person?
Do you integrate your news into real-time articles/posts on the site?

Design Appeal

Where do my eyes focus naturally focus on the site?
Are there any design element repeated?
Is the site attractive to look at? Why or why not?

For more on running a design review, see Scott Oberkun’s How to Run a Design Critique and Makiko Itho’s The Delicate Art of (Web) Design Critique.

Trends from the Analysis

If you go through each of these categories, you usually find something worthwhile to say. We analyzed six different sites: Quality Process SIG, Twin Cities, Heartland, Tech Editing SIG, Orlando, and the Contracting and Independent Consulting SIG.

The webinar description suggested that we would explore ways to build attractive online sites where members could interact and find value, because fewer and fewer people are physically gathering for meetings.

As we moved through the sites, it was clear that a lot of people were trying to move in exactly this direction — towards collaboration and participation. The Quality Process SIG adopted SharePoint to make it easy for numerous people to author content. Twin Cites integrated a social networking component in a custom CMS where members could friend each other, add personal details, and even write blog posts. Orlando was in the process of moving their content to WordPress because their old site was a “dinosaur.” The Tech Editing SIG built their content on a wiki platform containing a section that showed posts from their email list discussions in an automated way.

What’s Missing

To enable participation and collaboration, many of the platforms allowed you to comment, subscribe, interact, log in, and manage the content. This makes sense.

But the platform is only the first step. Whether you’re using WordPress, Drupal, Joomla, SharePoint, Ning, or any other Web 2.0-capable technology, a larger ingredient is missing from the recipe for a thriving online site where members naturally gravitate to for interaction. Your site can be as interactive as anything can be, and yet still remain dormant, unused, unexplored, rarely visited, and rarely even noticed unless you provide a reason for people to come together as a community.

For example, although the Twin Cities site offers the ability to friend others, blog, and add personal details about your location, interests, and other details, it isn’t generating the activity you see on Facebook.

What’s interesting about Facebook isn’t that it allows you to write on other people’s walls, provide status updates, or add other people as friends. What’s interesting is that so many people are on Facebook, checking it and posting to it daily or even hourly.

Is it possible to create an online platform that technical communicators would use with as much popularity as Facebook or Twitter or even Stack Overflow?

The problem, I think, is in gathering a critical mass of community. Chapters are so small, it’s hard to see much activity from members on a site. For example, our chapter now has about 20 members (as opposed to about 75 from last year). To think we’ll convert the site into a thriving hub of online interaction is an illusion. You need thousands of people to build up the exchanges that take place in a popular community. When you have the thousands of people coming to your site every day, they begin to interact, and the interactions fuel more comments and replies and posts. At some point, you have a thriving community. But you don’t build a community without a critical mass of participation.

Without a critical mass of people to form a community, you end up with a dormant-looking site — for example, what most chapter sites look like.

The Ning Community Scott Abel created comes closest to the thriving online site where members can interact, but even that site seems underused. I just logged into the other day for the first time in months.

Again, the main problem is in the critical mass. There just aren’t enough people in chapters to form a presence on a site. Chapters and SIGs fragment the already small online technical communicator audience.

Additionally, although SIGs have greater potential for online interaction, most of the activity is often better expressed through e-mail listservs and threaded forum discussions. As old-school as email or forums are, they’re fast, immediate, and reach almost everyone.

The Solution?

I’m not really sure what solution is for chapter and SIG sites to move from dormant sites to thriving hubs of interaction. Technical writers are a small niche of overall people on the web, and when you fragment that already small niche into even smaller groups of chapters and SIGs, they never seem to come together in a critical mass of people.

This problem isn’t unique to our group. It’s a problem that stems for many independent publishing locations and sites. Conversations are taking place on blogs here and there, email listservs here and there, forums here and there, and the consequence is a bunch of whispers that you can’t hear (unless you look in each of the individual places).

I believe the solution won’t involve centralizing the information/people into one site and location. Instead, it will involve aggregating the sources through RSS and other technology.

Blog Sponsors

Web Site Critique and WordPress Q&A Webinar This Thursday

Tom Johnson — Tue, 26 Jan 2010 15:33:58 +0000

Date: Jan 28, 2010
Time: 1 pm EST
Platform: Genysys (on the web)
Cost: Free for STC members
Registration required

Will Sansbury and I are giving a webinar on web design and WordPress this Thursday as part of the STC Community Leaders series. In the webinar, we plan to look at about five chapter/SIG sites in depth, examining what they’re doing well and how they could be improved. The sites will merely provide examples to spark discussion about web concepts and techniques (helping us move in a descriptive rather than prescriptive direction).

Here’s the description of the webinar:

Because most communities have far more virtual participants than physical participants, establishing a strong web presence where members can find information, interact with each other, and access resources is critical. In this community webinar, we’ll review a handful of chapter or SIG sites and discuss what’s working well and how they might be improved. We’ll also talk about WordPress — a popular platform many chapters are using for their websites. As a WordPress consultant, I deal with all kinds of WordPress questions, from customizing themes to implementing specific plugins, tweaking the stylesheet, inserting PHP tags, and fixing crashed sites. If you’re currently managing or implementing a WordPress site, bring your questions and I’ll try to answer them. I’ll also go over my top 10 recommended WordPress plugins. [Note: I wrote the description before asking Will to join me in the presentation, so excuse the first person point of view.]

If you’re planning to attend the webinar and you want your site critiqued, let me know. Otherwise, I’m thinking of looking at these five sites:

The webinar will have a WordPress bent to it, because it’s the platform I’m most familiar with. Technical how-to is always less interesting that concepts, so I only see the discussion veering off into WordPress when we mention ways to implement concepts/techniques in a practical, easy way. I’m also familiar with Joomla and Mediawiki, so if one of those solutions makes more sense, I’ll talk about them.

You can sign up for the webinar here.

Note: In my experience with Genesys, you have to call in via phone. You can’t use your computer speakers. So if you’re calling internationally, you might want to use Skype.