acrolinx conference 2013 - ibm

8.0

Welcome to:

June 2013

© Copyright IBM Corporation 2013

IBM learning teams: Experiences with Acrolinx

Julian Cable

Learning Development

IBM United Kingdom Limited

Acrolinx international user conference

San Jose, California

IBM Learning Development


Julian Cable: Introducing myself

• An IBM Accredited Learning Specialist

• Main roles:

– Courseware tools and standards specialist

– Lead technical editor

– Quality assurance for course development

• Focal point for Acrolinx usage in IBM education teams

– Quality Review Board (QRB – IBM governance board) member

– Acrolinx Advocates group member

• IBM Style and Word Usage Council member

• Professional member of UK Learning & Performance Institute

and British Computer Society

• Three years’ experience with using Acrolinx



IBM Education teams – overview (1 of 2)

• At IBM, Education is not a single IBM line of business but is

fragmented into separate teams aligned by product family.

– In some brands, part of Services (focus on revenue generation)

– In other brands, part of Information Development or Product

Development

• These teams vary in templates, tools, and offerings, and in

their business alignment.

• Frequent new acquisition companies join IBM.

• IBM authors hundreds of IT product training courses per year.

– Mixture of:

• Face-to-face classes

• Virtual classroom classes

• Self-paced virtual training



IBM Education teams – overview (2 of 2)

• Courses are run for internal and external clients, in 50+

countries around the world.

– Mostly taught in English, some local translation

– Each course can be several days long and contain hundreds of pages

of course material

– Courses can undergo multiple revisions by different authors over a

lifespan of 5-10 years or more

• Varied profile of course development personnel:

– Seasoned professional writers and editors, versus ad hoc subject-

matter experts with limited experience of writing standards

– Native versus non-native English speakers

– Widely dispersed geographically



What deliverables do education teams develop?

• Lecture material (slides, student notes, instructor notes):

– Either: Professional writers develop directly in Adobe FrameMaker

– Or: Casual subject-matter experts (SMEs) create initial content in

PowerPoint and an automated conversion to FrameMaker is run

afterwards.

• Exercises material (exercise instructions, lab setup):

– Either: Professional writers develop directly in Adobe FrameMaker

– Or: Casual SMEs create initial content in Word and an automated

conversion to (unstructured) FrameMaker is run afterwards.



When is Acrolinx run during course development?

• Acrolinx checks might be run at one or more of these stages:

– When initial PowerPoint or Word content is developed

• Currently, Acrolinx can check PowerPoint slides only, not speaker notes.

A new Acrolinx plug-in is due later this year to support speaker notes.

– Either on content that is developed directly in FrameMaker or after

initial content is converted to FrameMaker

– Some brands have a separate quality assurance (QA) team who

review content that course developers write.

• The QA team might run a further Acrolinx check, or review Acrolinx reports

that course developers generate and provide in PDF format.

• QA team editors might also perform cognitive editing on the content or

check for problems that Acrolinx did not catch.



IBM education teams: usage to date

• Pilot in Q4 2010

• In 2011:

– Learning teams started to adopt Acrolinx in production

– Created specific linguistic rule set for Learning domain

• Based on technical publications rule set with domain-level customizations

• Approximately 220 current Acrolinx users in education teams

– Spread across five IBM Software Group product families



Acrolinx adoption by IBM WebSphere Education

• Focus on the education team that uses Acrolinx most actively:

WebSphere Education

– 37 content developers (technical writers)

– 5 technical editors and quality assurance personnel

– 4 education development managers

– 1 education standards specialist



Why did WebSphere Education adopt Acrolinx?

• WebSphere Education has mandated Acrolinx use for all

course development since 2011:

– Improve quality and consistency of course materials

– Reduce unintended linguistic variations between courses that are

developed and edited by different individuals

– Enable all course developers, by regular Acrolinx use, to learn from

mistakes and adopt good writing practices and correct terminology use

– Reduce time that QA personnel spend on mechanical editing

– In medium term, reduce course development cycle time and cost



Acrolinx plug-ins deployment for Education

• New FrameMaker plug-ins:

– Support FrameMaker 10 and then 11

– Add a confirmation step when user requests Change All

– Preserve flags when saving a FrameMaker document

– Run check on entire FM book and generate a report for whole book

– When making edits after a check, run "live" check on changed content

to ensure new errors are not introduced (Recheck Selection feature)

– Add Check with Corrections Dialog feature

• New Word plug-in:

– Better support Word change tracking feature

• New PowerPoint plug-in:

– Support speaker notes (planned for 2013)

– Provide functional features more closely aligned with other plug-ins



New style rules added

• Some new style rules were requested

by Education and adopted by other

IBM domains. Other new rules were

set up by IBM ID and adopted by

Education.

– Agreement antecedent pronoun

– Avoid first person

– Avoid future tense

– Avoid polite expressions

– Avoid run-on sentence

– Avoid written number followed by number

– Check domain-specific word

– Comma with which clause

– Incorrect extra comma

– Incorrect semicolon

– Missing end of sentence punctuation (for

selected paragraph types)

– Missing word

– Sentence fragment (for selected

paragraph types)

– Too many spaces

– Use article

– Use comma after introductory adverb

– Use comma after introductory phrase

– Web capitalization

– Wrong preposition

– Wrong word (such as

would of > would have, loose > lose)



Examples of Learning rule set customizations

• Increase “sentence too long” threshold from 25 to 35 words

• Keep “avoid modal verbs” rule but allow “should” (to introduce

learning objectives)

• Suppress “use with caution” flag for “have to” when in negative

context of “do not have to”

• Exclude flagging of file extensions as unnecessary space

• Exclude flagging of noun followed by -ing in specific cases

• Exclude FrameMaker code example paragraphs and

PowerPoint monospaced text

• Allow CamelCase (mixed case) words

• Provide "Ignore in Whole Document" option for all spelling flags

• Suppress rules that apply only to DITA content (not currently

used in Education)



Terminology changes

• Submitted to Terminology team many additions, deletions, or

changes to terms for IBM dictionary.

• Stopped flagging words that are usually used correctly, such

as:

– page

– install

– output

– solution

– tab

– version

– visual



Custom dictionary

• Implemented custom dictionary feature (Education only), with Acrolinx QRB and Terminology team:

– Any writers can use Term Contribution to submit valid brand- or product-level terms to exclude from flagging as spelling errors.

– Using role-based permissions on Acrolinx Dashboard, QA personnel review submitted terms and standards team leader makes final decision about terms to deploy.

• Types of affected words include:

– Commands

– User IDs and passwords

– Variables

– Names of functions, applications, utilities, and components that are part of product names (not included in Terminology database)

• No plans to deploy custom dictionaries in User Technologies.

– (Some of these categories would be handled by correct DITA tagging.)



Custom dictionary example words

• Some example words (in bold red) that were added to custom dictionary:

– In an Internet Explorer browser window, open the Madisons store from your

favorites.

– The pwd command is used to output the path of the current working

directory.

– Log in to the administrative console as User ID wsadmin and Password:

web1sphere.

– After disconnecting from the surrogate ID, you can use IP at guestname

followed by .ilsvpn.ibm.com.

– Although a few sample Jython scripts are included in the command-line

interface directory, the original Jacl administration scripts still exist in the

Service Registry installation.

– The default GC policy, optthruput, attempts to optimize throughput for your

applications.

– A third GC policy, gencon, attempts to provide both optimized through put

and response times.



Acrolinx requests from IBM Education

• Enable checking of PowerPoint speaker notes

– I believe that this is coming soon!

• Handle Boolean conditional expressions with “Show as per Expression” option

– Without risk of content being hidden or deleted after a check

• Ignore all code example text in unstructured FrameMaker

– Ignore text by named character format or by font (Courier New)

• Do not mark a FrameMaker document as changed if a user did not run a check or make any changes.

• Show all term help items in same browser tab

– Opening a new tab for every term help item can leave an unworkable number of tabs open. No need to keep previous help items open.

• Provide a menu option to remove flags from selected text only, rather than from whole document.



Thank you!

• I hope you have found this session of interest.

• Any questions?



Backup:

Acrolinx feedback from a WebSphere Education editor

“I have tried various editing programs in the past and in every case I thought that they were more trouble than they were worth. To me, they actually slowed down the process because of the very high percentage of false positives that they raised. The Acrolinx tool is the first such program that I have found to be useful and helpful. As with any new software product, it does take a bit of time to get used to it, but I found that it soon becomes a comfortable and familiar tool. I liked the quick replace feature where it offered a replacement word and a single mouse click took care of the problem. In cases where it did not offer a replacement, the process of making the correction might take a bit longer, but it is still relatively quick and painless. The capability of a quick link to a web page to explain the reason for flagging a word or phrase can be useful if the reason for the flag is not immediately clear. I appreciate the fact that it has been customized to include the correct names for our products and to follow our IBM WebSphere Education rules and guidelines. I also appreciate that we can make suggestions and provide requests for changes to better suit our particular needs (for example, as was done to increase the number of words on the sentence-length trigger). I believe that consistent use of the Acrolinx tool will -- eventually -- shorten the total course development cycle while leading to better quality and consistency. I would never recommend it for use in writing a novel or a lyrical essay or an autobiography, but it is a good tool for our kind of specialized technical writing.”

acrolinx conference 2013 - ibm

Business

ibm education teams

ibm authors hundreds

product development

single ibm line of business

development personnel

information development

acrolinx usage

acrolinx checks