Robert Desprez Communications

HTML5 or EPUB: What is best for technical documentation?

by 2 Comments

When you cre­ate doc­u­men­ta­tion for tablets or smart­phones, should you cre­ate an EPUB file or an HTML5 file?  As usu­al, it depends on your audience.

What is an EPUB file and how does it differ from HTML5?

An EPUB doc­u­ment is an XML file that is zipped file with the .epub exten­sion. You cre­ate EPUB files using Microsoft Word, Adobe InDe­sign, and help author­ing tools such as Mad­Cap Flare and Adobe Robo­Help. This enables users to read the file in Adobe Dig­i­tal Edi­tions, or iBooks, Apple’s free e‑reader for iOS.

HTML5 is not soft­ware that has to be installed but rather a new ver­sion of HTML that appears in your brows­er. It’s a work in progress. Safari and Chrome pro­vide good sup­port for HTML5 where­as Inter­net Explor­er has been slow to sup­port it.

Why would you create an EPUB file?

The main advan­tage of an EPUB file is that is changes the flow of the text, based on the device you have. If your users are view­ing your con­tent on an iPhone, the pre­sen­ta­tion of the con­tent appears dif­fer­ent­ly than if it is viewed on a PC or an iPad. For exam­ple, see the fol­low­ing two screen shots:

EPUB file shown on an iPad
EPUB file shown on an iPad
EPUB on an iPhone
EPUB on an iPhone

With EPUB files, you can also choose the fixed lay­out option as well. Fixed lay­out EPUB files are per­fect for cook­books, illus­trat­ed books, and some text­books. With the fixed lay­out func­tion­al­i­ty you can embed fonts, choose par­tic­u­lar text sizes, and pre­cise­ly posi­tion images. Basi­cal­ly, fixed lay­out options give con­tent cre­ators greater con­trol over the pre­sen­ta­tion of a doc­u­ment. For the tech­ni­cal details of a fixed lay­out option for EPUB, see the Fixed Lay­out Doc­u­ment sec­tion of the Inter­na­tion­al Dig­i­tal Pub­lish­ing Forum web site.

One dis­ad­van­tage of an EPUB file is that it may require your users to install soft­ware such as iBooks, which is not pre-installed on iPads or iPhones.

Why would you create an HTML5 file?

You prob­a­bly want to con­sid­er cre­at­ing an HTML5 file when your users are run­ning browsers (such as Safari or Chrome) that sup­port it. If you are con­fi­dent that your users are using one of these browsers, it’s eas­i­er for them to view your work. There is no extra app to install.

Anoth­er advan­tage of HTML5 is that if your user assis­tance is avail­able in a brows­er, any revi­sions to the con­tent will imme­di­ate­ly be seen by your users. With an EPUB file, there’s the addi­tion­al work of cre­at­ing the lat­est EPUB file and dis­trib­ut­ing it again to your users.

HTML5 also sup­ports offline support—meaning that you can view the con­tent when you have an Inter­net con­nec­tion, your brows­er caches the con­tent, and then you can view the same con­tent when you are offline. This may be per­fect for users who need user assis­tance but do not have a reli­able net­work connection.

Other Resources

* What is EPUB 3? by Matt Gar­rish ( a free O’Reil­ly book).

* Eliz­a­beth Castro’s book EPUB Straight to the Point. 

* Test your brows­er for HTML5 sup­port

*A free online book: Dive into HTML5 by Mark Pilgrim.

Generating iPad content using RoboHelp 10

by 6 Comments

Robo­Help 10 makes it much eas­i­er to gen­er­ate EPUB files, the most wide­ly accept­ed file for­mat for e‑books. EPUB files can be read on an array of devices includ­ing the iPad, iPhone, and smart­phones run­ning on Android.

What is an EPUB file?

An EPUB doc­u­ment is a zip file with the .epub exten­sion. You cre­ate EPUB files using Microsoft Word, Adobe InDe­sign, and help author­ing tools such as Mad­cap Flare and Adobe Robo­Help. This blog entry explains the major steps of cre­at­ing EPUB files using Robo­Help 10, which was released this summer.

Advantages of EPUB

* Easy to pro­duce. Cre­at­ing EPUB files are easy to pro­duce with new­er author­ing tools.

* EPUB con­tent reflows. In Eliz­a­beth Cas­tro’s book EPUB Straight to the Point, she writes: “If you’re read­ing it (an EPUB file) on an iPhone, the width of the page is a fair bit small­er than if you’re read­ing it on an iPad, or on some oth­er read­er. The beau­ty of EPUB is that it flows the text to fit what­ev­er screen it’s on.” In con­trast, the pre­sen­ta­tion of a PDF file stays large­ly sta­t­ic, regard­less if you’re using a PC, a Mac, an iPhone, or an iPad.

* Can be viewed offline. Once you down­load a EPUB file, you can view it with­out an Inter­net connection.

Disadvantages of EPUB

* Nav­i­ga­tion is not ide­al. The EPUB file for­mat sup­ports a table of con­tents at the start of the EPUB file. But if you’re want­i­ng to skim the table of con­tents, you need to jump to the front of the doc­u­ment. A tra­di­tion­al online help sys­tem always dis­plays the table of con­tents, mak­ing it easy to jump to anoth­er topic.

* Best suit­ed to lin­ear read­ing. The EPUB file for­mat is fine for tra­di­tion­al books in which you read lin­ear­ly. Users of tech­ni­cal doc­u­ments do not read this way. They skip from top­ic to top­ic in an effort to find the answers they need.

* Extra app required. iBooks, Apple’s e‑reader app, is not pre-installed on the iPad. Users first need to down­load the free app before they can read EPUB files. Not a huge deal but it is anoth­er step for users.

Writing EPUB content in RoboHelp

I assume that you are famil­iar with Robo­Help so I don’t try to explain every option and con­cept in the soft­ware. I focus on what’s new in Robo­Help 10 and how it can eas­i­ly cre­ate EPUB files.

Step 1: Write your content in RoboHelp

Write your doc­u­men­ta­tion in Robo­Help as you nor­mal­ly would.

Step 2: Generate your content as an EPUB format

  1. In the Sin­gle Source Lay­outs sec­tion, dou­ble-click eBook.

Step 3: Select your options

General section
  1. In the eBook Set­tings dia­log box, click Gen­er­al.
  2. In the eBook For­mats sec­tion, select the EPUB 3 check box. You can also gen­er­ate an out­put file that is com­pat­i­ble with the Kindle.
  3. If need­ed, make changes to your out­put fold­er and file name.
  4. In the Options sec­tion, you may want to select the Val­i­date EPUB 3 Out­put check box. An open source tool called epub­check val­i­dates your EPUB file.

Content section
  1. In the eBook Set­tings dia­log box, click Con­tent.
  2. In the Table of Con­tents drop-down list, select the table of con­tents that you cre­at­ed in RoboHelp.
  3. In the Index and Glos­sary drop-down lists, select an index and glos­sary if you set them up in RoboHelp.
  4. In the Con­di­tion­al Build Expres­sion sec­tion, change your con­di­tion­al text set­tings if need­ed. With con­di­tion­al text, you can tag cer­tain sec­tions of your con­tent for dif­fer­ent audi­ences or deliverables.
Meta Information section
  1. In the eBook Set­tings dia­log box, click Meta Infor­ma­tion.
  2. In the Title box, type the name of the EPUB file.
  3. In the Author(s) box, type the name of the author. This may be your name or the name of your department.
  4. In the Publisher(s) box, type your com­pa­ny’s name.
  5. In the Descrip­tion box, type a sen­tence or two that pro­vides a good sum­ma­ry of your document.
  6. In the Cov­er Image sec­tion, select the image you’d like to be on the cov­er on your EPUB file.
  7. Click Save and Generate.

Step 4: Download Adobe Digital Editions

Adobe Dig­i­tal Edi­tions free soft­ware offers a way to view and man­age EPUB files and oth­er dig­i­tal pub­li­ca­tions. I think of it as soft­ware to quick­ly test your gen­er­at­ed file before trans­fer­ring the file to an iPad.

This step is option­al but could save you time if you intend to gen­er­ate mul­ti­ple EPUB files. When Robo­Help fin­ish­es gen­er­at­ing the file and you click View Result, you can imme­di­ate­ly view your EPUB file in Adobe Dig­i­tal Editions.

If there’s a prob­lem with the file, you can fix the issue and then quick­ly regen­er­ate the content.

Step 5: Transfer the file to an iPad

After you have gen­er­at­ed the con­tent, Robo­Help cre­ates the EPUB file in a fold­er that you specified.

To syn­chro­nize the file to an iPad, ensure you have iTunes installed on your com­put­er. In addi­tion, you need to install iBooks, a free e‑reader on your iPad.

  1. Con­nect your iPad to your computer.
  2. In iTunes, click the Sum­ma­ry but­ton and select the Man­u­al­ly man­age music and videos check box.
  3. Locate the gen­er­at­ed EPUB file on your computer.
  4. Drag it to your device in iTunes.

iTunes syn­chro­nizes the file to your iPad.

Step 6: View the file in iBooks

  1. Open iBooks.
  2. In the Library in iBooks, tap the file you just transferred.
    The EPUB file appears. Here is an exam­ple of an EPUB file that is dis­play­ing in iBooks.

If you want to know more about EPUB files, check out Eliz­a­beth Cas­tro’s book EPUB Straight to the Point. 

Are we facing a “skills gap” in Information Technology?

by 12 Comments

What new skills have you learned on your own time in the last six months?

If you’re like many IT peo­ple, you may be defer­ring to your boss when it comes to career devel­op­ment. Per­haps your com­pa­ny is ready to imple­ment a new Share­Point site and you’ve been immersed in that project for the last six months. Great. But have you been keep­ing your eye on indus­try trends on what skills are emerg­ing and those that are wan­ing? I sus­pect most peo­ple work­ing it IT would say “no.”

The June 4th edi­tion of Com­put­er­World mag­a­zine argues that com­pa­nies have lots of job open­ings but there are still many IT work­ers who are strug­gling to land jobs. The rea­son? A skills gap. The jobs are there but work­ers’ skills are not.

Todd Wein­man, a recruiter quot­ed in the arti­cle, said: “You can’t rely on a com­pa­ny for your growth and train­ing anymore…Except for a few enlight­ened com­pa­nies, if they’re train­ing you at all, they’re train­ing you for what they need, not nec­es­sar­i­ly train­ing for what you need to devel­op your tech­ni­cal skills over the long run.”

Employ­ers are clam­or­ing for can­di­dates with exper­tise in mobile app devel­op­ment, cloud com­put­ing, and busi­ness ana­lyt­ics, accord­ing to the arti­cle. But employ­ees may be tired of the self-devel­op­ment treadmill—especially if they are work­ing more than 50 hours per week.

Accord­ing to the arti­cle, here are some sug­ges­tions for thriv­ing in IT in the com­ing years:

* Cre­ate your own train­ing plan. Accord­ing a recent arti­cle pub­lished by the Har­vard Busi­ness Review, set aside a few hours each week on career development.

* Pur­sue train­ing and cer­ti­fi­ca­tions on your own time and at your expense. On a relat­ed note, I recent­ly read a book called the Six Fun­da­men­tals of Suc­cess by Stu­art R. Levine. Levine writes: “Take con­trol of your con­tin­u­ing edu­ca­tion and per­son­al growth.  Every six months, give your­self spe­cif­ic learn­ing goals…Too often peo­ple wait for their boss to tell them what skills they need. This is a stun­ning abdi­ca­tion of responsibility.”

* Devel­op soft skills, like com­mu­ni­ca­tion.

* Iden­ti­fy dif­fer­ent class­es of skills. Which tech­nolo­gies are emerg­ing, main­stream, and or lega­cy? Does your cur­rent exper­tise have a long future ahead of it? If not, what cer­ti­fi­ca­tions and train­ing do you need?

Here’s my take on it. I’ve worked about 15 years in IT and work­ers who enjoy learn­ing and are moti­vat­ed to learn appear to do bet­ter in the work­place. In con­trast, those employ­ees who decide to go on “career cruise con­trol” become vul­ner­a­ble dur­ing lay­offs because their skills are per­ceived to be “rusty.”

Obvi­ous advice? Per­haps. But many work­ers don’t seem to fol­low it. What do you think about this issue?

Check out the Com­put­er­World arti­cle.

 

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.

TECHNICAL WRITERS ARE RELUCTANT SELF-MARKETERS

by 5 Comments

I don’t know how many times I’ve talked to tech­ni­cal writ­ers who’ve said to me that they dis­like self-marketing.

If you’re employ­ee and you don’t like mar­ket­ing your­self, it may mean you suf­fer from a lack of vis­i­bil­i­ty with­in your com­pa­ny. Peo­ple know your name but they may not under­stand what you do or how you add any val­ue to the orga­ni­za­tion. If you’re a con­tract writer and you dis­like mar­ket­ing, the results can be more serious—a track record that is marred by long peri­ods of unemployment.

Why do tech­ni­cal writ­ers dis­like mar­ket­ing so much? Here are a cou­ple of guesses:

  • Most tech­ni­cal writ­ers are intro­verts. By their very nature, tech­ni­cal writ­ers don’t like to stand in the lime­light or toot their own horns. They enjoy work­ing alone, not net­work­ing, and cer­tain­ly not pre­sent­ing a top­ic to others.
  • They haven’t learned about mar­ket­ing. Many writ­ers I’ve talked to often wrin­kle their noses when talk­ing about mar­ket­ing as if it’s a dirty word.

Mar­ket­ing, in my mind, is vital to the ongo­ing suc­cess of an orga­ni­za­tion. As a con­tract writer, I believe it’s impor­tant to remind clients and prospects about who I am and the ser­vices I offer, even when I’m work­ing on a long-term con­tract. If you don’t remind peo­ple of the ser­vices you provide—whether it’s an e‑mail, blog post, or upcom­ing pre­sen­ta­tion you’re sched­uled to deliver—people for­get about you. And if they for­get you, you won’t hear about upcom­ing jobs.

Some­times peo­ple dis­like some­thing because they don’t under­stand it. If you’re a con­tract tech­ni­cal writer strug­gling with lin­ing up con­tracts and feel that mar­ket­ing is not your forte, I’d rec­om­mend you read Duct Tape Mar­ket­ing by John Jantsch, which pro­vides an excel­lent overview of mar­ket­ing activ­i­ties for a small busi­ness. Who knows? You might start enjoy­ing mar­ket­ing after all.

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