Updating Documentation Efficiently

Is there anyone out there that manages documentation updates efficiently??

This is a question I've asked myself and every search engine on the planet lately. So, let me explain a little bit about our conundrum. I feel it a bit premature to even be posting this, as it would be nice to have a solution worked out, but perhaps this will solicit a few suggestions from other readers.

Typically, our documents are meant to be printed and are formatted as such. Although I'm the only tech writer at my company, I work with a group of computer trainers, who also write documentation for end-users. We all generally work in MS Word and when files are published to our internal portal, we PDF them. So, essentially, we've got two copies of every file - one in Word, which is stored in our Document Management System (DMS), and one in PDF, which is on a server that feeds the portal interface for people to find help documentation. The tech documentation is in two places too - in Word format and stored in the DMS and also in a "tech knowledge database" that we've been using for years to keep technical knowledge and documentation in a shared space for all. You might be wondering why the DMS isn't considered a shared space -- it is, but it's a painstakingly slow process for people in other states and countries to access the documents in our document library here. We don't currently have a Content Management System in place....it's in the works, and has been for about 2 years. So, let's just say I'm not waiting for the CMS to be implemented to come up with a way to manage all of this stuff.

Well, as you can imagine, things have gotten a little out of hand. When you look at the latest updated document in Word, it doesn't match the latest PDF that was posted to the portal. Problem is, not everything we write in Word gets posted to the portal, so people "forget" to update what goes on the Portal. We've also introduced a wiki and some groups use that instead of the tech knowledge database. Some people prefer one over the other.

So, we need to come up with a system - to be more proactive in making updates. Best I can think of is that we have to make it mandatory to catalog every user-facing document we produce so that if we make a change it gets posted appropriately. The other issue that might be addressed by this is to alert us when the change we're making to one document should be made to other documents. For example, if something in the process itself changes (e.g., new server names or locations), we make that change to EVERY document that includes that information, not just the one we remembered to update. Seems like all of this should be automated, but aside from just creating a database of sorts with decent views and search capability, I'm at a loss. All of the solutions I come up with seem like we're creating much more work than should be necessary.

We'll be having discussions in our group over the next few weeks to get this moving, and I'll be sure to post updates.

In the meantime....any ideas out there you'd like to share would be most welcome.

Writing for the Web

I haven't had much experience writing for the web in an official capacity (not counting this blog, of course). But, I wondered what is different about writing for web v. print. Well, quite a few things, but I'll focus here on how web writers may address an audience's needs through their style of writing for the web.

First of all, who is your audience and why are they reading what you have written?

One stark difference in writing for the web v. print is that you have to consider how people will find your content to begin with. Writers for the web should be considering the use of relevant keywords that are used in web crawlers to index your content so people can find it. It's recommended that writers repeat these keywords 2-3 times to give it the right strength for a search. This can be a challenge - you don't want to make is sound like you're just throwing keywords all over the place - you lose credibility. Web writer should also be keeping the tone of the writing (for general audiences) conversational, rather than formal. If your audience is more technical, however, and you expect they are reading your content to be able to DO something, you need to be specific and write to their level. Often the product you are writing about will help determine who your audience is.

However, one major advantage of writing for the web is the ability to format your content in a way that doesn't overwhelm the readers and can address multiple audience's needs all at once. If you had a website for a product that could potentially have different audiences with different purposes, you could format your content in a way that allows the reader to determine which link to click on the home page to lead him or her to the content specific to their purpose -- it's a far cry from handing someone a 500-page manual and telling them to just use the index to find what they need. Keep in mind that some of your readers may need to accomplish different tasks, including: assessing information, learning about something, learning to do something, or need to do something directly as a result of reading your content. The last task is often true for content that is more technical or instructional in nature.

Take for example, a pharmaceutical website like Pfizer's. There could be a wide range of audiences going to their website -- consumers, health care professionals, investors, to name a few. Pfizer addresses this by titling certain sections with "For Health care Professionals" and "For Investors" -- the use of heading help the user know where to go for his or her particular need. They try to address different people's needs through formatting, layout and using links appropriately to assist their readers in getting to the information they need.

Layout is important, not only for usability, but also because people tend to read web pages in the F-Shaped Pattern. According to Jakob Nielsen, "Eye tracking visualizations show that users often read Web pages in an F-shaped pattern: two horizontal stripes followed by a vertical stripe." He goes on to say:

• Users won't read your text thoroughly in a word-by-word manner. Exhaustive reading is rare, especially when prospective customers are conducting their initial research to compile a shortlist of vendors. Yes, some people will read more, but most won't.
• The first two paragraphs must state the most important information. There's some hope that users will actually read this material, though they'll probably read more of the first paragraph than the second.
• Start subheads, paragraphs, and bullet points with information-carrying words that users will notice when scanning down the left side of your content in the final stem of their F-behavior. They'll read the third word on a line much less often than the first two words.

Unless people are reading your material to do something as a direct result, they're scanning your content and keeping the F-Shaped Pattern in mind is important. Additionally, web writers should take advantage of web features, like links and html....sounds pretty basic, really, but there are so many sites that just write for print and then post their documents in pdf format. They make is seem like providing a link to Adobe downloads for Adobe Reader is enough. It's not. It annoys readers if you simply post PDFs. Take for example, this NJ town's website. I realize this is a small-town website and they may not have many resources to beef up their website, but between their menus that make it difficult to find information to the fact that when you do find it, it's just pdf launching.....it's enough to make a person move to a more web-savvy town... (Not really....Maplewood is quite nice.)

Navigation is another thing web writers need to keep in mind. They may not be designing the website, but they should keep in mind how users will return to the content from the hyperlinks they provide, for example. Although print documents may have navigators through a table of contents and index, it's a different layer in the web.

Keeping your audience in mind for print materials means putting together a nice table of contents and index (for larger documents) as well as using clean headings and titles. Some of this is similar to the web, but as we can see, this is done differently - from making your website findable through relevant keywords (and meta tags as well) to formatting it in a way that different audience's needs may easily be presented without being overwhelming.