I’m not entirely sure what a product would look like that integrates these two elements, because technical writing usually lacks both visuals and story. It usually consists of dry technical procedures written in a list, meant to be read in any order, and stripped down to its most minimalistic expression.

So perhaps what I’m envisioning is a different kind of deliverable, rather than a remake of an existing deliverable. I’ve grown accustomed to creating the following standard deliverables:

• Webhelp (HTML)
• How-to Guide (PDF)
• Quick Reference Guide (PDF)
• Video Tutorial (flash)

Now there’s one more to add to this list: visual storytelling guide. This guide doesn’t compete with the other standards we maintain. We still write the traditional online help file. We still create quick reference guides and videos. But with the visual storytelling guide, we let our hair down a bit more and not worry so much about the economy of information as we unravel story after story coupled with strong images and possibly video.

The visual story begins with a character. In most cases, you would create a user persona based on user research. You then give this user/character a name and context. Then give the character a problem (a scenario). The character would then attempt to solve the problem, and in so doing, the reader learns how to perform various tasks.

Harry Miller is probably the best example of someone who is already doing visual storytelling. His visual stories about using Microsoft Outlook replace the dry documentation that people otherwise might not read. Check out this series of video storytelling episodes complete with actors, scenes, and dialogue.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

After writing the post, I tried to embrace the outsider mindset and hunker down at my desk to go about my work. Working under this metaphor, I realized that I was no longer moving toward a solution, but merely providing documentation to address something others had already created. I felt a sense of emptiness and lack of purpose.

One of my colleagues, Derek, shared with me a new metaphor he recently adopted to describe technical writing. He had a bitter experience on his first project in our organization when one of the project managers told him the tech writer’s role is to document “what is, not to suggest what should be.” Now Derek has come to think about technical writing as a kind of janitorial job. He said,

At the end of the day, we’re really janitors. I know it may sound derogatory and even offensive, but our job is to clean up other people’s messes. Project managers don’t want to see us, they don’t want to interact with us. They just want us to arrive after the work is done; they want us to come in and do our jobs quietly, cleaning up the spills, vacuuming the crumbs, taking out the trash — all without complaint or objection.

Such a mindset is not only uninspiring, any writer with a keen eye for language and a good analytical mind will be unfulfilled in such a role, and Derek knows it. Playing the janitor, acting as an outsider, or as  Gryponmountain puts it, playing the monk in LadyHawke whose job it is to describe the broken stairs and other areas of decay and hazard in an old decrepit cathedral, will lead the once-aspiring technical writer to burn out and seek another career. At our core is the drive to create, not to clean up.

But there’s another dimension to this problem, and it’s a more important one. Putting aside all resentment about playing a janitorial role, language experts should play a more active role in shaping the interface because the interface is text. As such, writers do a disservice to project teams if they don’t play a role to help clarify and sharpen the interface language.

Of course the interface also has a good bit of graphics and design, but largely what users interact with is text. This assertion is most striking when you actually remove the text from the interface you’re using. For example, here’s the text removed from the WordPress interface.

The WordPress interface with all text removed

Go ahead and create a new post, timestamping it to be published next Monday, add a category and change the author. What, you can’t do that? You could probably still format the content with the rich text editor’s buttons, but what kind of content are you creating — a page, a post, or something else? And what is that pushpin at the top doing?

Here’s the text removed from the Snagit interface.

The Snagit interface with all interface text removed

Go ahead and create a menu delay capture, add a border around it, and set the default file type to be PNG and stored in the D:// drive. Again, it’s difficult to do this without text, and only possible if you already know the application.

Here’s the text removed from the Youtube admin interface.

The Youtube interface with no text

Upload a new video and tag it with your website title, and then select to play it in HD with captions. Again, it’s impossible to do much of anything in the design itself, as simple as the interfaces are in each of these examples. The user needs to the text to navigate and understand the interface.

What Kind of Writing Is Interface Text?

Writers are often skilled in all types of language forms, from short poems to letters to essays to how-to text. But the text on an interface is a different kind of text. If you isolate the text from the design elements, you lose a lot of the meaning, similar to what happens when you remove the text from the design.

The design adds meaning to the words. When designers choose a typeface for the text, it adds meaning. The hierarchy, the position on the page, the background color, the bold or italic formatting, the relationships and proximity to other elements, the length of text, the text’s placement in the user’s line of vision, the accompaniment of icons — all of these design elements give context to the text, so that you’re no longer just playing with words and deciding on the right word. You’re trying to find the right word in the right context.

The Challenges of Word Choice

Designers attempt to add meaning through design elements, but the greatest challenge designers and project managers face in interface text is probably word choice. How many times have you seen a word used in an interface you’re documenting that just doesn’t seem to fit? Users need to reconcile a banking statement. Committee members can submit a linked item. Building schedulers can allocate resources. To stop spam you activate Akismet. Bloggers can burn a feed. Analysts can drill down into the data. Content managers can configure the slug for each URL. When you upload an image, the message you see says Crunching. In every instance, the word choice is probably wrong. It doesn’t communicate plain understanding to the user.

In addition to the wrong word, other times the problem is inconsistency. When you finish making edits, you Save / Submit Changes / Commit. If you don’t want to save your changes, you can Cancel / Discard / Go Back. To set up a recurring series in a calendar, you can choose to set up a repeating event, and later you can edit the recurring event.

Finding the right word for the context is a skill. It often involves discovering the language of your users — through interviews, observations, or other feedback — rather than sitting in a project meeting and reasoning it out.

In an upcoming post I’ll dive into more principles for interface text. But my overall point here is that the interface consists mainly of text, and because of this, writers (language experts) need to help shape and craft this interface language.

You can’t influence the interface text if you’re brought on to the project team one month before it’s released. By that time, quality assurance engineers are already running their regression testing and preparing to hand it off to infrastructure for release. Developers have already used the same terms on multiple screens, dialog boxes, error messages, database tables, and throughout the application code. Unless there’s a major problem with the words, no one will be inclined to change them. The project manager sees no pressing need to make language changes so late in the game, because everything seems to be working just fine prior to release. No customers have complained yet, so it’s easiest to leave it alone.

Some Research Supporting Early Involvement of Writers

If you want to insert yourself early on the design process, the first step is to believe that you belong there. You are a word expert. The interface is full of words. In Text Treatment and User Interface,  Tobias Komischke notes,

Before graphic user interfaces, text was the primary means of both input and output defining human-computer interactions. Even today, much of the information user interfaces present is textual. Therefore, we should notunderestimate how the right text treatment can measurably improve user productivity and increase user satisfaction.

In other words, when interaction designers present their prototypes for the new application interface, they’re not just presenting a design. They’re working with words and designing text with meaning in everything from buttons, labels, page titles, error messages, dialog boxes, tabs, drop-down boxes, notes, and other interface text. Writers should be present during the design meetings. We understand the nuances of language more than any other project team member.

In Art and the Zen of Web Sites, Tony Karp says,

In a successful advertisement it’s the graphics that grab you,  but it’s the text that does the selling.

While designers would disagree that graphics only catch your attention, certainly almost no one can get by without text. The user interface becomes incomprehensible. But you can still often get by even if you strip out the stylesheet and images.

Apple, the king of intuitive interface design, stresses the importance of clear, consistent text and recommends including a writer  in the development process. The Apple Human Interface Guidelines state:

Although Mac OS X uses graphics as a primary means of user-computer interaction, text is prevalent throughout the interface for such things as button names, pop-up menu labels, dialog messages, and onscreen help. Using text consistently and clearly is a critical component of interface design.

Your product development team should include a skilled writer who is responsible for reviewing all user-visible onscreen text as well the instructional documentation. The writer should refer to the Apple Publications Style Guide for guidance on Apple-specific terminology.

Is text a “critical component of interface design”? Of course. Take the text away and the user can do nothing. Involving the writer early to get the text right can make a huge impact on usability.

The Microsoft Developer library also encourages involving the writer early on in the design process. In an entry on User Interface Text, the Microsoft authors say:

Software developers often think of text as relegated to product documentation and technical support. “First we’ll write the code, and then we’ll hire someone to help us explain what we have developed.” Yet in reality, important text is written earlier in the process, as the UI is conceived and coded. This text is, after all, seen more frequently and by more people than perhaps any other type of technical writing.

Comprehensible text is crucial to effective UI. Professional writers and editors should work with software developers on UI text as an integral part of the design process. Have them work on text early because text problems often reveal design problems. If your team has trouble explaining a design, quite often it is the design, not the explanation, that needs improving.

I find it reassuring that the two biggest companies in software, Apple and Microsoft, both recommend involving the writer early in the development process to shape the language of the user interface.

Regardless of what companies and style guides recommend, writers will need to prove their worth to earn a seat at the table. As such, writers will need to be familiar with best practices for including text in the interface. In my next post, I will explore best practices for adding interface text.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

The key trends are as follows:

• Help is embedded in a browser because the browser is the predominant mode people use to find information.
• Search is the main method for navigating content. There’s still a table of contents, but no more index.
• When you choose a topic, you see contextual topics related to the topic you’re viewing.
• You can choose to include online content into the search.
• The help is “decoupled” from the Visual Studio application, so the help authors can update the help without waiting for the next release of Visual Studio. (This is what I referred to in my content independence post.)

The direction the Visual Studio Help team is moving reflects my own trends as well: moving towards a web-like experience with help, relying more on search, adding contextual topics based on what the user is viewing, and publishing help in a location I can update on the fly.

(Thanks to Keith Soltys for the link.)

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

1. A good SharePoint site is one that doesn’t look like a SharePoint site.

SharePoint provides push-button site publishing, so creating a site takes literally 3 seconds. But all the sites look the same. Having an out-of-the-box SharePoint theme, just like everyone else, makes you look like a novice, on par with the completely untechnical depts who can barely operate SharePoint, much less customize it.

Here’s what the default theme looks like.

More importantly, SharePoint has a lot of negative baggage. All those poorly organized, neglected, outdated SharePoint sites immediately come to the user’s mind. Do you want your SharePoint site mixed in with this negative baggage? No. You want your site to gather respect from your users. A little awe. Not a sigh and an “oh, another pathetic SharePoint site” response.

Customizing your Sharepoint site should definitely be in the plans. But before you run forward, make sure you actually can run. SharePoint has three basic levels of rights access: server admin, site collection admin, and site admin. If you only have site admin rights, you’re at the mercy of your site collection admin as far as customizations go. If you have site collection rights, you have a lot more customization power. And if you’re a server admin, you can do almost anything (and probably break everyone’s site in the process).

If you’re only a site admin, stop here. You can’t customize much of anything. Sure, SharePoint allows you to pick about a dozen different incredibly ugly themes, but they all shout SharePoint. If you’re a site collection admin or server admin, keep reading. There are additional themes that don’t look anything like a SharePoint site, but they’re hidden away.

To view these alternative, hidden themes, which look nothing like regular SharePoint sites, you have to activate the Office SharePoint Server Publishing Infrastructure feature at the site collection level. See the following image.

(You can click any image to see the full size at a crisper resolution.)

After you activate the publishing feature at the site collection level, you can then activate the publishing feature at the site level. Once activated, you have a whole new world of customization features available to you. You’ll also notice that the Site Actions menu has about three times as many options on it.

With the publishing features activated, go to your settings, and under the Look and Feel column, click the Master Page link (this link only appears after you activate the publishing features). Select a new master page, such as Blueband.master, my favorite. See the following image.

Here you can also select inheritance properties for master pages and stylesheets. In other words, you can determine whether the subsites inherit the Blueband.master theme from the parent site. And you can select the CSS file your site uses (choose Band.css).

Note: I’m not sure that the Blueband.master is a “theme,” rather than just a different master file. But it seems like a new theme to me. In contrast, the default “themes” available at the site level, such as Vintage, are really just color variations.

2. Without SharePoint Designer, you can do nothing. With SharePoint Designer, you can do nothing.

If you don’t have SharePoint Designer, you can do very little in customizing your site. That said, SharePoint Designer isn’t very useful. It provides a box of tools in the upper-right, as if you could just insert buttons and controls to modify your site. But the toolbox requires advanced knowledge.

SharePoint Designer is only useful in that it gives you access to the stylesheets and allows you to make minor edits to some of the pages. Beyond that, you need to be a SharePoint programmer to really modify the page. The page’s code is not basic HTML or XML. Additionally, much of it is heavily nested in tables.

3. Like the Borg, all content pages render through Default.master or another master file.

SharePoint’s files are all incestuously interconnected. If you’ve seen the Borg, from an episode of Star Trek, it works the same way. The Borg is a collection of individual people that are all controlled through a central person. In SharePoint, that central person is the master file. If you’re using your default theme, it’s the Default.master file. If you’ve selected Blueband, then Blueband.master is your master file.

When you create a page (by going to Site Actions > Create a Page), you’re not creating a page that exists independent of the master. The content page renders through the master, or uses the master to render.

You access the master by going to _catalogs > Masterpage > Blueband.master in SharePoint Designer (at the site collection level). The master has numerous content placeholders, which you see when you open the master in SharePoint Designer. These content placeholders also exist on the content pages that render through the master.

If you delete a content placeholder on the master, it breaks all the pages that use the master to render. So be sure you leave content placeholders alone.

What if you don’t want one of those content placeholders? Well, you can actually delete it. When you open a content page, you’ll see an error message prompting you to find the content placeholder you deleted. Just delete the placeholder from the content page as well and it’ll work.

4. When you edit the master, the core.css file unghosts.

An interesting thing about SharePoint is how it hides the stylesheets. Core.css is the main stylesheet that styles the default.master (and subsequently every other page). But core.css exists at the server level, not the site collection level. It’s only when you start editing the master file that the core.css file “unghosts” and copies down to your site collection level.

To unghost the core.css file, put your cursor somewhere on the master page and change the font through the CSS panel on the left. After saving your changes, you might see core.css suddenly appear as a new tab. It is then permanently available in the _styles folder of your site.

Notice I said “might.” Actually, if you’re using Blueband.master, there are at least two main CSS files that style the page: core.css and band.css. If you edit the wrong part of the master page, band.css might appear instead of core.css. At any rate, I don’t think band.css unghosts from the server in the same way that core.css does, although to be honest I’m not sure. In my setup, core.css unghosts at the site level, while band.css is available at the site collection level.

Regardless of how you accomplish it, changing the styles through the core.css file and the band.css file is key to customizing your SharePoint site.

5. You can’t see the image directory that the core.css stylesheet refers to.

As if the confusion over stylesheets wasn’t enough, images are also problematic. First, there are two sets of images: images that belong to the blueband.master file and images referenced in core.css. The blueband.master images are available in the site collection level under Style Library > en-us > Images. If you open that folder up in Windows Explorer, you can quickly drag those images to your desktop and start modifying them in Photoshop.

But where are the images referenced by core.css? Remember that the core.css file originally exists on the server and is only copied down to the site collection level after you start modifying your master file. Well, the images don’t come along for the ride. If you want to change an image referenced in the core.css file, you have to download the image from your site (by right-clicking and downloading the image or by noting the file name and path in the core.css stylesheet and then inserting it in your web address so you can view and then download the image).

After you download the image, you can’t upload it to your server image directory unless you have access to the server, and even if you did, it might change that image for all other SharePoint sites on that server.
So you upload the image to a picture library on your site. Then replace the original URL in the core.css stylesheet with the new URL.

Now, you may think that by deleting, overriding, or completely annihilating the images in either Blueband’s image location or uploading new images to replace core.css you would actually be successful in replacing the previous image. Nope. Though they appear live and published to you, until you check in and publish your images and files, others can’t see your changes. If you can sign into the site as another user (somewhat tricky if it’s all the logins are automatically synchronized with Active Directory), you can see what others see. At that point, you’ll know if you’ve checked in and published your images properly.

Here’s the interface where you must publish your images. (Note: If Approve is also an option, do that too.)

You can shoot yourself in the foot by removing the versioning settings of the document library where your images are stored. If you edit the library’s settings and choose no versioning, you don’t have an option to publish the images, and I believe they never show. I know that I spent a while pulling my hair out before I figured out what was wrong.

6. If you edit the Summary View and change the item limit, it breaks the code and you have to generate a new site to figure out the code to fix it.

Do you think I’ve hit on some unintuitive processes for web design? Wait until you read this one. There’s a nasty bug in SharePoint that actually breaks the code if you make a certain modification to a blog site. Open up the category view of a blog, and then edit that category view.

Change the item limit for the default summary view of that category. Bam, it just broke some code. When you click a category now, only one item in the category shows, rather than all posts of that category.
The details aren’t something I want to delve into here. But basically to fix the problem, you have to open the category page in SharePoint Designer and replace some code with the same code from a working site.

Open the category.aspx page in SharePoint Designer. Select the Split view, and then select the Posts web part in the Design view. Then in the Code view, look for listxmlview and replace that entire part with code from a new SharePoint category.aspx page (using the same selection).

I’m not kidding about this. You might not want to make too many modifications to the default category views if you’re using a blog site.

7. If you modify a theme, switch back to the default, and then return to your modified theme, all modifications are gone.

There’s something else you should know about modifying themes. When I first started modifying a theme, I started modifying one of the pre-built themes you can choose without slipping into the Publishing features. I switched to Vintage, modified a bunch of files for an hour or two, and then switched it back to the Default theme because I realized modifying Vintage would take me all day due to the massive number of images and the inability to actually access them in mass.

When I switched back to Vintage, I discovered, in an unpleasant way, that all my changes were gone. It seems that each time you select one of these themes, SharePoint copies down the theme’s files anew from the server, overwriting any changes you made to the theme.

After that, I decided not to switch back and forth between themes, so I can’t say that the same is true for master pages like Blueband. Still, you might want to back up your modifications before switching around those master files/themes.

8. To configure the search to see just blog posts, you have to enter a code that does not exist anywhere on the Internet or help file.

The way I set up my SharePoint site, I chose a blog site and created about a dozen views of the blog posts. Views define specific ways of looking at the same information. For example, one view may include only certain categories, another view may include only the post titles, and so on.

When I searched for a file using SharePoint’s search box, the search results showed all of my view pages first before the actual blog post files. As a result, the search was worthless until the second or third page of results.

Fortunately, SharePoint does allow you to configure the search at the site collection level. You can set a scope with a specific search rule, and then modify the search web part to use that scope. I wanted the scope to return only blog posts, and not any view pages. To do this, you need to enter a certain contentclass code into the scope at the site collection level. This content class does not exist anywhere online that I’ve been able to find. Here it is:

contentclass = STS_ListItem_Posts

The following image shows where you enter that contentclass.

You may also want to restrict the results to a specific folder, such as http://yourdomain.org/blog/lists/posts. Once you set up this scope, the results are much better.

One thing I could never figure out is how to configure the best bets search. Supposedly, SharePoint allows you to enter synonyms for searches and then specify the results. For example, let’s say you use the term “meetings” in your help, but your users also use the term “agenda.” You can create a best bet so that when users search for agenda, the search results show URLs you’ve selected. But I was never able to get this feature working.

9. You can’t control the look and feel of the admin side of things.

You may have spent weeks creating a beautiful interface for your users. But there’s one ugly truth that will scare away anyone with collaborative purposes: the admin side of SharePoint can’t be skinned (at least not without some tricky programming).

As long as users aren’t creating posts, or editing wiki pages, or doing anything on the admin side, they won’t know that the admin side still shows the default SharePoint style. But if they do need to go into the admin view, the experience can be jarring, as they go back and forth between themes.

You can’t create a seamless experience with your new SharePoint site. You can only customize the clothes, not the body, so to speak. Here’s what the Blueband master looks like as users view your SharePoint site.

And here’s what the same site looks like when you enter the admin side of it.

Nothing at all like the external interface. By now many of you reading this may be thinking, I’m never touching SharePoint. SharePoint is such a kludge of an application; no way I’m ever using that. Here’s one more little surprise for you.

10. Site metrics don’t tell you what post anyone has viewed.

Admittedly, one appeal of using SharePoint when it’s integrated with Active Directory is to see not only the names of your visitors, but the posts they viewed. However, if you’re using a blog site, get ready for some disappointment: you can’t actually see which posts visitors viewed. The metrics entice you with informative looking color graphs, but when you start trying to piece together the information, it’s missing a component: the actual post name.

This is because I was using a blog site, and the pages I wanted to track were the posts. Surprisingly, posts are actually stored in a database somewhere, unlike wiki pages or other content pages.

The same metrics problem isn’t true if you have a site with a lot of pages. Still, it proved somewhat unclimactic for me. I even attached some hit tracker code onto the post template, but it didn’t propagate to the individual posts.

Conclusion

With all these quirks, it’s hard to see why SharePoint is so popular. I suspect it’s popular because none of these serious flaws are apparent until you try to customize your site, and 99% of the time people leave the sites as is.

Even despite these quirks, if you’re company uses SharePoint, you may be stuck with it. Once you get these concepts down, however, SharePoint is a workable solution as a file repository, a website, and a corporate blog. SharePoint does provide a ton of collaborative features with almost no custom coding. Few other platforms can make the same claim.

Follow-up note: A couple of months later, after fully migrating my help content to SharePoint, I decided the platform had too many disadvantages for help authoring (for example, you can’t export your content into different formats). I now use SharePoint only as a file repository and landing page for my help content.

In this podcast, Microsoft Usability Researcher Hugh McLoone talks about Microsoft’s Natural Ergonomic Keyboard 4000. Hugh originally gave this presentation to the Puget Sound (Seattle) SIGCHI group on January 25, 2007. SIGCHI stands for Special Interest Group for Computer-Human Interaction.

Heidi, who attended the presentation, says, “As you’ll hear, Hugh was a driving force behind the ergonomic keyboard. This podcast will appeal to technical writers both from the perspective of usability and also from the perspective that we type all day and can benefit from hearing about ergonomic keyboards and preventive health issues.

The presentation is approximately 35 minutes, and the Q & A session has been removed for the sake of brevity.” For more information, see this post on Heidi Hansen’s blog. Music is from Podshow.