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.

More reasons to limit your computer time

by 5 Comments

Most of know that sit­ting in front of a com­put­er for pro­longed peri­ods is bad for your body. A new book titled Your Brain on Nature argues that com­put­ers may also be low­er­ing our IQ, mak­ing us less empa­thet­ic, and more narcissistic.

Authors Eva Sel­hub and Alan C. Logan argue the following:

  • IQ may be low­er­ing. James Fly­nn dis­cov­ered that IQ rates were increas­ing about three to five IQ points per decade in the 20th cen­tu­ry, due to bet­ter nutri­tion, school­ing, health care, and oth­er social fac­tors. Unfor­tu­nate­ly, accord­ing to Sel­hub and Logan, stud­ies from dif­fer­ent devel­oped nations have report­ed a decline in IQ start­ing in the late 1990s. With the explo­sion of all things wireless—smartphones, com­put­ers, tablets, and video consoles—we’re inun­dat­ed and dis­tract­ed to the point that it affects our abil­i­ty to com­pre­hend infor­ma­tion. Here’s an excerpt from the book: “In the course of a 40-minute study peri­od, a sim­ple tex­ting exchange (less than three min­utes) will slash a student’s word recall in half.” Anoth­er exam­ple: a sin­gle e‑mail inter­rup­tion will con­sume about 24 min­utes for the aver­age worker.
  • Nar­cis­sism is sky­rock­et­ing. A recent study com­pares nar­cis­sis­tic atti­tudes in stu­dents between 2009 and 1994. Based on the answers the stu­dents pro­vid­ed, 89 per­cent more stu­dents appear to be more nar­cis­sis­tic than in 1994. High lev­els of nar­cis­sism appear to be cor­re­lat­ed with fre­quent dai­ly vis­i­tors to Face­book. Nar­cis­sism is a psy­cho­log­i­cal con­di­tion char­ac­ter­ized by an inflat­ed sense of self-worth and decreased empathy.
  • Empa­thy rates are decreas­ing. Many of us in North Amer­i­ca are using social media to con­nect with co-work­ers and friends. Yet for all this online con­nect­ed­ness, we’re appar­ent­ly not any more car­ing. In one study, the authors cite that “scores of empa­thet­ic concern…have dropped 49 per­cent since 1980.”
  • More screen time may lead to high­er rates of death. In a 2011 study of more than 4,500 adults fol­lowed over sev­er­al years, total screen time was asso­ci­at­ed with a 52 per­cent high­er risk of death.

Talk about a wake up call. I fre­quent­ly spend more than eight hours per day in front of a com­put­er. To mit­i­gate this seden­tary time, I try to walk or run sev­er­al times a week. If this research is cor­rect, I may be fur­ther cur­tail­ing my time online.

Is writing for mobile the next big thing?

by 10 Comments

With all the news about the sky­rock­et­ing demand for smart­phones over­tak­ing com­put­er pur­chas­es, you might think that tech­ni­cal writ­ers would increas­ing­ly need to focus on writ­ing and deliv­er­ing user assis­tance for mobile devices.

For tech­ni­cal writ­ers, writ­ing for mobile appears to be the next big thing. Here are a few examples:

  • Mobile devices will be the pri­mary con­nec­tion tool to the Inter­net for most peo­ple by 2020, accord­ing to the Pew Research service.
  • Ref­er­ences to mobile phones and tablets are abun­dant at the Writ­er­sUA con­fer­ence and the upcom­ing Soci­ety for Tech­ni­cal Com­mu­ni­ca­tion conference.
  •  Help author­ing tools such as Mad­Cap Flare and Robo­Help tout that they sup­port pub­lish­ing con­tent for mobile devices using the ePub output.
  • There’s even a book ded­i­cat­ed to the top­ic called Devel­op­ing User Assis­tance For Mobile Apps by Joe Welinske.

So along with social media, one might think that cre­at­ing user assis­tance for mobile devices will rev­o­lu­tion­ize the way we work. There’s one prob­lem though.  In the last year, I have yet to see one job descrip­tion in Van­cou­ver that explic­it­ly refers to prepar­ing con­tent for mobile devices. When it comes to tech­ni­cal writ­ing oppor­tu­ni­ties, Van­cou­ver is no Sil­i­con Val­ley but it’s not unusu­al to see five to 10 adver­tised jobs per month.

I don’t think any­one can argue that cre­at­ing user assis­tance for mobile devel­op­ment is too new. Accord­ing to Apple’s web site, there are report­ed­ly 500,000 appli­ca­tions for the iPhone and iPad. There are also thou­sands of appli­ca­tions that run on the Android oper­at­ing sys­tem.  And smart­phones have been avail­able for years. So why is there not a surge in demand for user assis­tance for mobile devices? Some guesses:

  • Soft­ware devel­op­ers are writ­ing the con­tent. While the user assis­tance writ­ten by devel­op­ers may not be pro­fes­sion­al­ly writ­ten and for­mat­ted, per­haps man­age­ment feels that the con­tent  is “good enough”? After all, if a mobile app requires a lot of doc­u­men­ta­tion, it prob­a­bly means that it’s dif­fi­cult to use. Users expect apps to be simple.
  • Per­haps writ­ing for mobile is not big as pre­dict­ed. Employ­ers in Van­cou­ver are not clam­or­ing for writ­ers with mobile expe­ri­ence.  To be fair, I searched for “tech­ni­cal writer mobile” on the U.S. job site www.dice.com and found that 41 of 649 jobs men­tioned “mobile” in the job descrip­tions. Hard­ly a tsunami!
Do you think writ­ing user assis­tance for mobile will be the next thing? Why is there not a stronger demand? I’d be inter­est­ed in your thoughts.

 

Three reasons you should allow comments in your documentation

by 9 Comments

Mil­lions of peo­ple around the world are post­ing blog entries and com­ment­ing on those posts. But tech­ni­cal writ­ers have remained on the side­lines by not let­ting our users com­ment on our content.

Here are three rea­sons you should enable commenting:

Rea­son #1: Peo­ple are used to writ­ing com­ments on blogs and web pages. Mil­lions of peo­ple post blog posts. And thou­sands of us add our com­ments to those posts. For the most part, tech­ni­cal writ­ers haven’t embraced this fea­ture. I’d haz­ard a guess that most online help or even sup­port web pages do not sup­port user comments.

I recent­ly read Clay Shirky’s book Cog­ni­tive Sur­plus. Shirky argues that in decades past North Amer­i­cans spent a lot of time watch­ing TV. But with the Inter­net, peo­ple are spend­ing much less time pas­sive­ly sit­ting on the couch. We’re par­tic­i­pat­ing online writ­ing blogs, cre­at­ing YouTube videos, and writ­ing and edit­ing con­tent on web sites like Wikipedia. Just a small change in how peo­ple spend their time can have aston­ish­ing changes in our world. He writes:
“Imag­ine that every­thing stays 99 per­cent the same, that peo­ple con­tin­ue to con­sume 99 per­cent of the tele­vi­sion they used to but 1 per­cent of that time gets carved out for pro­duc­ing and shar­ing. The con­nect­ed pop­u­la­tion still watch­es over a tril­lion hours of TV a year; 1 per­cent of that is more than 100 Wikipedias worth of par­tic­i­pa­tion per year.”

So the Inter­net has rev­o­lu­tion­ized how we spend our free time. As cit­i­zens and con­sumers, we are active­ly con­tribut­ing to con­tent. But tech­ni­cal writ­ers have remained on the side­lines by not let­ting our users com­ment on our content.

Rea­son #2: Col­lab­o­ra­tion helps cre­ate an online com­mu­ni­ty. Col­lab­o­ra­tion offers a num­ber of benefits:

* An online com­mu­ni­ty can help each oth­er share solu­tions, workarounds, and trou­bleshoot­ing tech­niques. Tech­ni­cal writer and author Anne Gen­tle writes in her book Con­ver­sa­tion and Com­mu­ni­ty : “…a com­mu­ni­ty of prac­tice can form now that online tools speed up the process of teach­ing spe­cif­ic tech­niques and learn­ing them from oth­ers.” Work­ers can spend about a third of their time look­ing for infor­ma­tion. An online com­mu­ni­ty is one of the ways that users can find infor­ma­tion quickly.

* An online com­mu­ni­ty builds good­will among your users. If your com­pa­ny has seri­ous­ly invest­ed a lot of time and mon­ey in an online com­mu­ni­ty with facil­i­ta­tors that respond help­ful­ly and quick­ly, the com­pa­ny slow­ly builds pos­i­tive good­will among its users. Over time, your com­pa­ny may be rec­og­nized as an inno­v­a­tive provider of support―potentially a dif­fer­en­tia­tor when com­pared to your competitors.

* An online com­mu­ni­ty can improve your con­tent. We all have blind spots. Maybe your online help doesn’t con­tain the key con­tent that users need. Per­haps they’re look­ing for specifics on a dif­fi­cult task. With an active and engaged com­mu­ni­ty, it won’t be long before some­one starts point­ing out the miss­ing pieces in your content.

Rea­son #3: Learn­ing new skills for writ­ers. Tech­ni­cal writ­ers are used to inter­view­ing SMEs, and draft­ing and edit­ing con­tent. By post­ing your doc­u­men­ta­tion and act­ing as a facil­i­ta­tor for user com­ments, you may learn about blog­ging soft­ware and HTML (depend­ing on which tool you use), and online diplo­ma­cy. Anne Gen­tle writes: “Con­sid­er becom­ing a mod­er­a­tor only after you have been a par­tic­i­pant for a while. Most online com­mu­ni­ties do not rec­og­nize any sense of enti­tle­ment that you may have because of your employ­er. Instead you must earn the community’s trust and offer real help, even if you only pro­vide links to your online help. Teach­ing the com­mu­ni­ty to fish (for infor­ma­tion) feeds them longer than just answer­ing ques­tions with­out cit­ing how you learned the infor­ma­tion yourself.”

Of course, I should point out that enabling com­ment­ing is no guar­an­tee of doc­u­men­ta­tion nir­vana. You may be sub­ject to spam­mers, your com­pa­ny needs to devote at least one per­son to mon­i­tor and respond to user com­ments, and you’ll prob­a­bly notice that a minor­i­ty of your users are the most like­ly to comment.

Here are a few exam­ples of online doc­u­men­ta­tion that encour­ages online dis­cus­sions and comments:

Microsoft’s Devel­op­er Net­work is one of the first exam­ples of com­mu­ni­ty-con­tributed content.
http://msdn.microsoft.com/en-us/library/ff851953.aspx#6

Atlass­ian allows users to post com­ments on its doc­u­men­ta­tion wiki.
http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home

On a relat­ed note, I wrote a blog entry about how to add com­ments to your doc­u­men­ta­tion using third-par­ty tools, such as Dis­qus and Wufoo.

Optimizing your online help for Google

by 5 Comments

Tech­ni­cal writ­ers not post­ing their online help sys­tems to a serv­er that can be accessed and indexed by Google take the risk that their con­tent becomes over­shad­owed by a third-par­ty author­i­ty such as a sup­port forum, said Joe Welinske, pres­i­dent of WritersUA.

In the same way that mar­keters have employed Search Engine Opti­miza­tion (SEO) to improve the vis­i­bil­i­ty of cor­po­rate web sites, online help that can be indexed by the search engines can pro­vide faster answers to your cus­tomers and poten­tial cus­tomers who are using Google, Yahoo, and Bing.

Here are my thoughts on the advan­tages of adding online help to a pub­lic location:

* Your con­tent is giv­en a much wider audi­ence. Instead of lim­it­ing your read­ers to the peo­ple who have bought your prod­uct, your online help can be made avail­able to any­one on the Inter­net. If a cus­tomer is strug­gling with a fea­ture of your prod­uct, he or she could find the answer using Google’s search.

* The rules of sup­port have changed. Peo­ple expect quick and rel­e­vant answers with the wide­spread use of Google. Even with the pos­si­bil­i­ty of social media sites super­sed­ing search engines, 92 per­cent of us still use search engines reg­u­lar­ly. For exam­ple, when I have a prob­lem with some­thing I own, such as a DVD play­er, I might look up the prob­lem in the print­ed user guide (if I still have it!), go to the manufacturer’s web site, or just type the name and mod­el of the DVD play­er in Google. From my expe­ri­ence, Google often pro­vides results that are as use­ful as the manufacturer’s sup­port web site.

* Adding online help to a pub­lic serv­er may ben­e­fit the company’s brand. For exam­ple, tech­ni­cal writer Sarah Mad­dox of Atlass­ian said that the company’s doc­u­men­ta­tion web site attracts more traf­fic than the company’s cor­po­rate web site.

Why are writ­ers not adding con­tent to a pub­lic serv­er? A few reasons:

* We are strapped for time. We don’t have the time to move our con­tent to a serv­er that can be accessed by Google’s webcrawlers that troll and index mil­lions of web pages.

* Com­pa­nies are reluc­tant to post detailed infor­ma­tion to a pub­lic serv­er. Con­ceiv­ably, com­peti­tors could read the details of a fea­ture in your online help and emu­late it. Oth­er com­pa­nies may be wor­ried of secu­ri­ty breach­es. But, in many cas­es, an exter­nal source may already be writ­ing about a company’s prod­uct or ser­vice, said Welinske, who pre­sent­ed at the Jan. 17th meet­ing of the STC West Coast chapter.

* We lack the inter­est or knowl­edge. We may lack the inter­est or the know-how to port the con­tent to a pub­lic-fac­ing serv­er. You need to con­sid­er the type of help you’re gen­er­at­ing, the HTML tags that are embed­ded in each web page, and the for­mat­ting of your help.

Here are some best practices:

* Types of help. If you’re plan­ning to post your help, cer­tain file for­mats work well, such as web pages, Web­Help, and PDFs. Old­er file for­mats such as Microsoft Help (i.e. CHM files) or Flash are not the best choices.

* Opti­miz­ing meta-tags. To help webcrawlers index the con­tent in your help, spend some time adding HTML tags to each top­ic. You need to dou­ble-check the title tags, review your key­words, and add rel­e­vant hyper­links to your help. See my ear­li­er blog post Mak­ing Online Help SEO Friend­ly.

* Social media. Incor­po­rat­ing social media in your online help is a way to fos­ter an online com­mu­ni­ty of users. See my ear­li­er arti­cle on Mar­ry­ing Twit­ter with User Doc­u­men­ta­tion.

* For­mat­ting and pre­sen­ta­tion. In his pre­sen­ta­tion, Welinske sug­gest­ed you need to add nav­i­ga­tion ele­ments and com­pa­ny brand­ing on all pages so that users know that the con­tent is the company’s mate­r­i­al. When you search for con­tent using a search engine, it strips out the table of con­tents and index so that each page should iden­ti­fy that the con­tent is the company’s doc­u­men­ta­tion. In addi­tion, include the last date that the con­tent was updat­ed and which ver­sion the doc­u­men­ta­tion addresses.

* Reg­is­ter your online help with the search engines. It’s worth­while reg­is­ter­ing your online help with Google, Bing, and Yahoo. You can reg­is­ter Google using Google Web­mas­ter Tools. It’s also valu­able to sub­mit a XML sitemap of your online help to search engines. Sitemaps are a way to tell search engines about all of the pages in your online help.

Writ­er­sUA pro­vides train­ing to tech­ni­cal writ­ers and hosts an annu­al conference.

Good pre­sen­ta­tion!

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