Robert Desprez Communications

SharePoint 2010 for technical writers

by 7 Comments

When I first start­ed using Share­Point, I have to admit that I was not impressed.

The user inter­face felt unin­spired. Some soft­ware user inter­faces draw you in. For me, Share­Point was­n’t one of them. I remem­ber won­der­ing, “Why would I want to use this?”

I’ve changed my tune. After learn­ing more about Share­Point’s ben­e­fits and using it at sev­er­al client sites, I rec­og­nize that it offers a num­ber of ben­e­fits to tech­ni­cal writers:

* Share­Point pro­vides a basic Con­tent Man­age­ment Sys­tem (CMS). Peo­ple use a CMS to pub­lish, edit, and man­age con­tent, such as doc­u­ments. A full-blown CMS is expen­sive where­as Share­Point is fre­quent­ly already installed in larg­er orga­ni­za­tions. Tech­ni­cal writ­ers can use it to gain con­trol over their doc­u­ments at the file level.

* Share­Point Foun­da­tion 2010 is free. Share­Point 2010 is avail­able in two flavours: Share­Point Serv­er 2010 and Share­Point Foun­da­tion. Share­Point Serv­er offers more fea­tures than Share­Point Foun­da­tion but the lat­ter is free.

* You can use meta­da­ta to tag your files. If you are work­ing on a lot of con­tent, adding meta­da­ta to your files may be a worth­while invest­ment because it helps group your con­tent into cat­e­gories. Meta­da­ta is a col­lec­tion of cen­tral­ly man­aged terms that you can define and then use as attrib­ut­es for a file. Then, after you have tagged your con­tent, oth­er writ­ers can search for doc­u­ments using the same categories—content is eas­i­er to find and update.

* Source con­trol. Share­Point requires you to check out files before you edit them and offers ver­sion con­trol of the file. Ver­sion con­trol essen­tial­ly keeps a his­to­ry of the file. If for some rea­son you want to res­ur­rect an ear­li­er ver­sion of a doc­u­ment, Share­Point makes it easy.

* Col­lab­o­ra­tion. Share­Point enables teams to col­lab­o­rate on files. If you are work­ing with anoth­er per­son on a file, each writer can work on the con­tent con­cur­rent­ly and the lat­est ver­sion is then uploaded to the Share­Point site.

* Doc­u­ment con­trol. Share­Point makes it pos­si­ble to restrict users at the site lev­el. Best prac­tices sug­gest assign­ing employ­ees or con­trac­tors to user groups.

* Work­flows. In Share­Point, you can auto­mate the review process. As a writer, you can cre­ate a list of review­ers and add dead­lines. Share­Point then sends e‑mails to SMEs and sends you an e‑mail when they have reviewed the document.

* Trans­la­tion work­flows. If you need to trans­late your con­tent, Share­Point can assist with the process by remind­ing exter­nal stake­hold­ers to per­form tasks by cer­tain dates, and e‑mails you when all of the work is complete.

* Easy to use. Share­Point has a sim­i­lar look and feel to oth­er Microsoft Office prod­ucts. It sports the famil­iar Microsoft rib­bon and the tasks are pret­ty straight­for­ward (for tech­ni­cal writ­ers, at least).

* Lots of sup­port con­tent. There are many books, web sites, and blogs about Share­Point. For exam­ple, check out these online train­ing courses.

The bot­tom line: Share­Point is a worth­while tool if col­lab­o­ra­tion is impor­tant and you need con­trol over your source files. Sounds like a good fit for most tech­ni­cal writers.

FIVE WEB ANALYTICS METRICS FOR TECHNICAL WRITERS

by 4 Comments

By using Google Ana­lyt­ics tech­ni­cal writ­ers can dis­cov­er what con­tent they write is pop­u­lar, how long users read their con­tent, and where their cus­tomers live. This blog post is a sum­ma­ry of the main points I dis­cussed at my recent pre­sen­ta­tion at the Writ­er­sUA writ­ing con­fer­ence in Long Beach, California.

What is Web Analytics?

First off, web ana­lyt­ics enables tech­ni­cal writ­ers to see how users access your intranet, sup­port web sites, and even help sys­tems that are host­ed on a web serv­er. Some writ­ers that I’ve talked to seem to think that web ana­lyt­ics is com­pli­cat­ed to set up and use. Actu­al­ly, set­ting it up is pret­ty sim­ple, assum­ing you’re com­fort­able with adding a bit of Google’s code to your HTML page. Ana­lyz­ing your data is also pret­ty sim­ple for our purposes.

Why It’s Important for Technical Writers

I believe web ana­lyt­ics is impor­tant for two reasons.

First, it pro­vides insights into how your users are find­ing your site, how they explored it, and how tech­ni­cal writ­ers can enhance their expe­ri­ence. Most of us work in orga­ni­za­tions where there are lim­it­ed resources and a large of queue of work. With web ana­lyt­ics, you can quick­ly dis­cov­er the num­ber of peo­ple review­ing your con­tent for a giv­en peri­od (month­ly, quar­ter­ly, or even dai­ly), and which doc­u­ments are pop­u­lar and which doc­u­ments are large­ly ignored.

Sec­ond, with web ana­lyt­ics, I think that it’s quite pos­si­ble that our writ­ing will be monitored—even scrutinized—in cer­tain orga­ni­za­tions that are inter­est­ed in see­ing the effec­tive­ness of each doc­u­ment and sup­port top­ic we write.

Tris­tan Bish­op, a blog­ger and senior con­tent strate­gist, wrote about the use of web ana­lyt­ics and how it will change our jobs:
“It won’t be long before you’ll know which of your top­ics are mak­ing a pos­i­tive dif­fer­ence, which need some help and which can sim­ply dis­ap­pear. It will soon be painful­ly obvi­ous which team mem­bers are writ­ing the high-impact top­ics, which are writ­ing the unin­tel­li­gi­ble top­ics and which are writ­ing the irrel­e­vant top­ics.” Ouch.

What Can You Measure

For a free tech­nol­o­gy, it’s amaz­ing what you can dis­cov­er using Google Ana­lyt­ics. You can mon­i­tor the num­ber of vis­i­tors com­ing to your site or help sys­tem for a spec­i­fied peri­od, the num­ber of new vis­i­tors ver­sus return­ing vis­i­tors, the aver­age length of time users spend on your site, the key­words they use in a search field, the coun­try they live in, the brows­er they use to access your con­tent, and much more. In fact, if you’re inter­est­ed, you can keep tabs on dozens of met­rics. But for tech­ni­cal writ­ers, I think there are just a hand­ful of met­rics you might want to keep an eye on.

  1. Over­all traf­fic vol­umes. This is impor­tant because it gives you a sense how many peo­ple are read­ing the con­tent you write and sup­port. You can start per­form­ing com­par­isons of this month’s traf­fic ver­sus the pre­vi­ous month’s traf­fic. Are num­bers going up? How is it relat­ed to sup­port calls?
  2. Vis­it dura­tion. In gen­er­al, the longer a per­son spends on your site, the more like­ly he or she will return. In con­trast, if a per­son stays only a few sec­onds, you may deduce that there is noth­ing of val­ue to the user.
  3. Bounce rates. Strict­ly speak­ing, a bounce occurs when a vis­i­tor looks at just one page of your help or web site and then leaves the site quick­ly. If a vis­i­tor comes to your intranet or sup­port site and then imme­di­ate­ly clicks the Back but­ton, it’s con­sid­ered a bounce. If your bounce rate is high (expressed as a per­cent­age such as 50 per­cent), you may be draw­ing the wrong type of per­son to your intranet/site.
  4. Search key­words. Using ana­lyt­ics, you can track the most com­mon key­words that users search for while using your sup­port web site or help sys­tem, pro­vid­ing insight into the con­tent that cus­tomers want. So this may help you understand:
  • What are cus­tomers look­ing for and strug­gling with?
  • What are the most com­mon phras­es when peo­ple are searching?
  • As a writer, do you need to change the way you describe a pro­ce­dure or con­cept so it’s more in line with the way cus­tomers think of it?
  1. Top pages and con­tent. Know­ing what vis­i­tors are seek­ing out can help you tai­lor con­tent for them and help you prune the con­tent that isn’t being used. This may help you focus your efforts when it comes to under­stand­ing the best way to spend your time.

Setting Up Google Analytics

Google has done a good job of explain­ing how to set up web ana­lyt­ics on your web site or online help. For more infor­ma­tion, see http://www.google.com/analytics/discover_analytics.html

Oth­er resources worth reviewing:

Web Ana­lyt­ics: An Hour a Day by Avinash Kaushik
Kaushik’s blog: http://www.kaushik.net/avinash/
Web Ana­lyt­ics Demys­ti­fied by Eric T Peterson
Author Anne Gentle’s blog entry on web ana­lyt­ics:
http://justwriteclick.com/2010/09/01/web-analytics-for-technical-documentation-sites/
Google Ana­lyt­ics by Jer­ri L. Ledford

MARRYING TWITTER WITH USER DOCUMENTATION

by 11 Comments

I just got back from the Writ­er­sUA tech­ni­cal writ­ing con­fer­ence yes­ter­day in Long Beach, Cal­i­for­nia. As I expect­ed, I attend­ed many real­ly inter­est­ing sessions.

Here’s one great idea. Sarah Mad­dox, an Aus­tralian tech­ni­cal writer, works at Atlass­ian, the com­pa­ny that devel­ops JIRA (bug and issue track­ing soft­ware) and Con­flu­ence (web-based cor­po­rate wiki soft­ware). She and her team cre­at­ed wiki doc­u­men­ta­tion that com­bines tra­di­tion­al tech­ni­cal doc­u­men­ta­tion, social media, and links to relat­ed blog posts. Here’s a screen capture:

 

This screen cap­ture shows a sam­ple of Atlassian’s wiki doc­u­men­ta­tion, which includes a Twit­ter stream at the bot­tom of the page.

If users tweet on a giv­en top­ic, they’re reward­ed by giv­en an online badge that they can add to their own blogs or social sites.

Sarah and her col­leagues at Atlass­ian have pulled off a rare feat—content that mar­ries tech­ni­cal doc­u­men­ta­tion, social media, and even viral mar­ket­ing. Because users who decide to tweet are offered an online badge, oth­ers might see the badge on anoth­er site and then tweet as well, which could lead to more and more users con­tribut­ing to the dia­log via Twitter.

This project won the most inno­v­a­tive idea at the Writ­er­sUA “peer show­case.” I think it’s a great idea and well deserved.

MY PRESENTATION AT THE UPCOMING WRITERSUA CONFERENCE

by Leave a Comment

I’m real­ly look­ing for­ward to attending—and presenting—at the upcom­ing Writ­er­sUA con­fer­ence in south­ern Los Ange­les on March 13–16th.

I’m deliv­er­ing a ses­sion called “Using Web Ana­lyt­ics for Improv­ing Con­tent” in which I’ll be talk­ing about why tech­ni­cal writ­ers should care about web ana­lyt­ics, key web site met­rics that writ­ers can mon­i­tor, and how to set up web ana­lyt­ics for a web site or an online help system.
I’m equal­ly excit­ed about some of the oth­er ses­sions that are sched­uled. Here are a few:

  • Com­par­ing the strengths and weak­ness­es of Help Author­ing Tools. This com­par­i­son includes Author-it, Doc-to-Help, Flare, Robo­Help, and Web­Works ePub­lish­er. Most of my career I’ve used Web­Works or Robo­Help so I’m def­i­nite­ly inter­est­ed in see­ing how the oth­er tools mea­sure up.
  • Lever­ag­ing user-gen­er­at­ed con­tent in tech­ni­cal doc­u­men­ta­tion. If you’ve been mon­i­tor­ing my blog over the last two months, I’ve writ­ten a cou­ple of entries about social media and tech­ni­cal documentation.
  • Tak­ing advan­tage of HTML5. Par­tic­u­lar­ly I’d like to know if there’s any­thing I can do to incor­po­rate this tech­nol­o­gy into tech­ni­cal com­mu­ni­ca­tion deliverables.
  • Writ­ing tech­ni­cal doc­u­men­ta­tion for mobile devices. This includes devices like the iPhone and iPad.

Of course, there are many oth­er top­ics, includ­ing a lot of ses­sions on writ­ing, DITA, and oth­er technologies.

HOW COULD CLOUD COMPUTING CHANGE OUR JOBS?

by 9 Comments

Cloud com­put­ing is one of those terms you hear a lot about. Microsoft recent­ly launched a “To the cloud” adver­tis­ing cam­paign. Google offers Google Docs, a suite of cloud-based office soft­ware. I’m work­ing on con­tract for a com­pa­ny that makes gov­ern­ment soft­ware that runs on Sales­force, anoth­er cloud-based com­pa­ny. So it’s notable that there’s lit­tle dis­cus­sion about cloud-based author­ing soft­ware for tech­ni­cal writers.

Cloud com­put­ing basi­cal­ly means soft­ware than runs on the Inter­net ver­sus soft­ware installed on your com­put­er. Adobe FrameMak­er uses the tra­di­tion­al mod­el: you down­load it from Adobe’s site or insert a DVD into your com­put­er and the soft­ware is installed on your hard dri­ve. In con­trast, Google Docs is acces­si­ble via your web brows­er instead of installing it. Once you log on, it’s instan­ta­neous. No more wait­ing for the instal­la­tion. No more punch­ing in long, com­pli­cat­ed ser­i­al numbers.

Soft­ware like Google Docs is catch­ing on. While it’s cur­rent­ly viewed as a “lite” ver­sion of Microsoft Office, it’s improv­ing all the time. Google is also look­ing at cre­at­ing an offline mod­el in case you’re work­ing at a loca­tion that does not have Inter­net access.

For tech­ni­cal writ­ers, there’s not a lot of dis­cus­sion about writ­ing using cloud-based author­ing tools. Think about the benefits:

  • Your soft­ware would be avail­able imme­di­ate­ly. No more waits for a large and some­times slow down­load from a vendor’s web site. I recent­ly down­loaded Adobe’s Tech­ni­cal Com­mu­ni­ca­tion Suite and the process took more than two hours.
  • Your upfront costs are low­er. Cloud-based soft­ware is fre­quent­ly priced on a sub­scrip­tion mod­el. So instead of pay­ing $2,000 for Adobe Tech­ni­cal Com­mu­ni­ca­tion Suite, you would pay a month­ly fee to access Adobe’s soft­ware on the Inter­net. I’d read­i­ly agree to a month­ly fee of say $55 ver­sus $2,000 for a suite of software.
  • Your soft­ware sub­scrip­tion would ide­al­ly pro­vide you with the lat­est ver­sion of the soft­ware. Instead of pon­der­ing whether I should upgrade to FrameMak­er 10, which was just released, my sub­scrip­tion would imme­di­ate­ly give me access to the lat­est features.
  • Col­lab­o­ra­tion could be eas­i­er among writ­ers. As the soft­ware resides on a remote serv­er, you could prob­a­bly store your source files there too. If done secure­ly, this could make col­lab­o­ra­tion eas­i­er. Imag­ine if you need­ed to share your files with a team in India. No more e‑mailing large files.
  • Tech­ni­cal reviews could also be done via the cloud. So instead of crank­ing up Word or Acro­bat on a com­put­er, review­ers could read your mate­r­i­al by review­ing a doc­u­ment that is avail­able on a web site.

Of course the mod­el isn’t per­fect. Per­for­mance, for exam­ple, could be an issue. But if soft­ware ven­dors can ensure a secure envi­ron­ment and offer decent per­for­mance, I think the idea has a lot of merit.

Recent Blog Posts

About Me

Robert Desprez I have worked as a Vancouver technical writer for more than 20 years, working at Kodak, Boeing, Teck Resources, and FortisBC. In addition, I have worked as a writing instructor at Simon Fraser University in Vancouver.

Contact Me

Robert Desprez Com­mu­ni­ca­tions Inc.
North Van­cou­ver, British Columbia
Canada
Phone: 604–836-4290