© 2010 ibm corporation maximo documentation: past – present - future andi couilliard 14 january,...

© 2010 IBM Corporation

Maximo Documentation:Past – Present - Future

Andi Couilliard

14 January, 2010

© 2010 IBM Corporation2

Our goals here

YOU:

Learn a little something about:

– Who creates your documentation

– How we've done it

– Where we are headed and why

– How we'll get there

ME:

Listen to what you have to say (make sure we're on the right track)

Open the doors to develop a new rapport or two

Answer your questions (as best I can)

... and, of course, have a little fun along the way


Agenda

Maximo information development team– Who we are– What we do

Maximo documentation: past and present– PSDI/MRO Software documentation– IBM Corporation documentation

Maximo documentation: the future– Why change?– Our goal and direction– Our focus– Our strategy– How we'll get there

What's new on the horizon?

How you can help

Questions


Maximo information development team: who we are

What is “information development” (ID) and what's it all about...

Then: – “...oh, they're just the documentation folks...”– Common titles and skillsets:

• technical writers• desktop publishers

Now: – “...oh, they're the folks that focus on user needs, content, and information design...”– Common titles and skillsets:

• information developers• technical writers• knowledge engineers• graphic artists• programmers• UI engineers• user advocates



Who makes up our team...

Maximo core and add-on products

14 writers

Over 130 years combined expertise!

Maximo industry solution products

10 writers


ID team support and leadership

1 second-line manager

2 first-line managers

1 information architect

1 quality/technical editor

1 quality/tools support




Where our team is located...

United States Canada Brazil Ireland



Our leadership team/contacts...

Management

Masha Maule ([email protected])

Andi Couilliard ([email protected])

Andrea Daniela Diniz ([email protected])

Information architecture

Allen Dean ([email protected])

Quality and technical editing

Elizabeth Wilde ([email protected])

Quality and tools

Maureen Hern ([email protected])


Maximo information development team: what we do

What we develop/produce:

Online help

Field help

Messages

UI text

Product manuals/guides

Information center topics

Fix pack and hot fix readme files

Maximo wiki (we administer this)

What we do not develop/produce:

Training materials

Redbooks

White papers

Support documents (technotes)

Marketing brochures


Maximo documentation: past and present

Versions 4.x and 5.x

Delivered technical guides and online help– Online help– Field help– Install guides– User's guide– System administrator guide– Report admin. and developer

guide– Application developer guide– Technical reference guide– ERP guides (SAP, Oracle,

PeopleSoft)– Workflow implementation guide– Finance manager guide

Distribution: CD and printed format

Tools used: Microsoft Word and RoboHelp

Focus/goals

Improved accuracy of technical information

Documented all UI task information pertaining to the product

Increased the quantity of information – provided much more thorough information

Included information in multiple locations when needed

Issues

Little customer interaction

Lots of duplication in information

Once released, data was rarely updated

The past: PSDI and MRO Software



Version 6.x

Delivered technical guides and online help– Online help– Field help– Install guides– User's guide– System administrator guide– Report administrator and

developer guide– Application developer guide– Technical reference guide– Database comparison report– ERP guides (SAP, Oracle,

PeopleSoft)– Workflow implementation guide– Finance manager guide– Multisite administrator guide

Distribution: CD only (no longer printed formats)

Tools used: FrameMaker and RoboHelp

Focus/goals


Documented all UI task information pertaining to the product

Improved consistency in information

Consolidated information (removed redundancies)

Started to gather and incorporate some customer feedback

Issues

Still lots of duplication in information

Guides expanded in size, making searches difficult

The past: MRO Software/IBM Corporation



Version 7.x

Delivered technical guides and online help– Online help– Field help– Install guides– Product reference guide– System administrator guide– Report administrator guide– Application developer guide– Integration guide– Migration manager guide– Workflow implementation guide– Finance manager guide– Multisite administrator guide

Distribution: DVD and online information center (Web)

Tools used: FrameMaker and RoboHelp primarily, limited Arbortext Editor

Focus/goals


Documented UI task information pertaining to the product

Improved consistency in information

Consolidated information (removed redundancies, reorganized information)

Gathered customer feedback and developed new strategies

Migrated toward topic-based writing

Issues

Some information was lost during consolidation effort

Once released, updates have not been made

The present: IBM Corporation


Maximo documentation: the future

Customer pain points and feedback– I can't find what I'm looking for easily– Information isn't always kept up-to-date– The information is spread out among too many large guides– You document the things I don't really need– The help I need is somewhere else - not available in the screen where I'm working– I can't search through all the documentation to find what I need

New technologies– DITA– Viewlets– Videos

New development methodologies– Agile

New forms of communication– Information centers– Wikis

Why change?



Deliver the right information,

in the right place, at the right time

Our goal and direction



Validate our assumptions about your information needs

Keep your focus as we influence the design of the product

Improve the consistency of the information among all Maximo-related products

Follow iterative development processes (for example, Agile)

Our focus



Improve quality of content, messages, and field help

Improve findability

Improve navigation

Improve accessibility

Increase knowledge of realistic user roles

Shift from low-level tasks to business process flows and concepts

Improve customer feedback mechanisms

Our strategy



Agile development methods

Embedded assistance

Progressive disclosure

Integration with other product teams

Collaboration with other information development groups

More consistent and focused contact with you, our customers

New tools, processes, and standards

and we'll keep on chugging...

How we'll get there



Time frame:– Began using Agile methodology for our first project in 2009

Pilot project:– IBM Maximo Asset Management Scheduler

Plans moving forward:– Use Agile as standard development method for all Maximo-related products

Benefit

Keeps your focus as we influence the design of the product– Input on field labels and other UI elements

Increases interaction with business partners

Validates our information design model as we go through multiple iterations

Agile development methods



What it is– Embedded assistance encompasses all text that users encounter in all types of

products, including• Labels and field names• Titles• Descriptive text in the UI• Hover text• Messages• Command names

• From presentation by Andrea Ames. STSM, October 2008

Benefits

Either you don't get stuck, or you get 'unstuck' faster

Lets you keep working in the product, not searching for the answers

Helps to clarify or answer something right where you need it, or, said another way...

Delivers the right information in the right place at the right time

Embedded assistance



OK, so now that you know a ~little~ bit about

'embedded assistance'...

POP QUIZ

» Embedded assistance is like:

A) A rose

B) A dog barking

C) Aspirin

D) A cold beer

E) Both C and D

F) None of the above

I know, it's not easy.

Bet you're wondering where I'm going with this...



POP QUIZ ANSWER

» Embedded assistance is like:

A) A rose

B) A dog barking

C) AspirinD) A cold beer

E) Both C and D

F) None of the above

WHY????Because it makes your pain go away...(OK – I'll accept C, D, or E for correct answers)



What it is• “... a technique for designing user interfaces that reduces complexity by

revealing only the essentials for a current task and then reveals more as users go further.”

From the Embedded Assistance Patterns page on the IMUI wiki

– Reveals information in an ordered manner– Provides only the information that is needed– Provides a clear trail– Connects the pieces to help form the 'bigger picture'

Benefits

Helps you to focus on what's important to you– For novice users: hides advanced features that aren't useful– For power users: Removes clutter

Lets you decide whether or not to drill down to the next level of information

Delivers the right information in the right place at the right time

Progressive disclosure


Maximo documentation: the future Progressive disclosure (continued)

Ins ta lla tio n o r c o nfigura tio n info rma tio nInfo rma tio n c e nte r to pic s6

O v e rv ie w o r re fe re nc e info rma tio nL ink to s uppo rting info rma tio n5

D e s c riptio n o f fie ld, it 's func tio n, c o nte xtF ie ld he lp4

E rro r me s s a ge te xt, re c o v e ry a c tio nsM e s s a ge s3

E xa mple s , de fa ult v a lue sIns truc tio na l te xt in UI2

F ie ld na me sUI la be ls a nd s trings1

E x a m p le sE le m e n ts (in o rd e r o f p ro g re s s io n )



OK, so now that you know a ~little~ bit about 'progressive disclosure'...

POP QUIZ

Progressive disclosure is more like:

Option (A)... ...or Option (B)



POP QUIZ ANSWER

Progressive disclosure is more like:

Option (B)•WHY????

•Because...

• Information is revealed in an organized way

•You can decide how far to drill-down

• It provides a trail to connect the pieces to the bigger picture



Maximo Asset Management is a 'base' platform for other Tivoli products, including:

– Tivoli Asset Management for IT

– Change and Configuration Management Database (CCMDB)

– Service Request Manager (SRM)

– Tivoli Provisioning Manager (TPM)

Frequent collaboration with the other Information Development organizations that release the Maximo-related products

– Hold regular weekly meetings

– Share 'best practices'

– Develop standards and guidelines for all Maximo-related solutions

– Reuse information topics among products

– Collaborate to improve the consistency among the Maximo-related products

Integration with other products / collaboration with other Information Development teams



Improved customer contact and feedback from the following:

– Attendance at Maximo advisory council group meetings

– Feedback from attendees at Pulse conference

– Business partner sessions during Agile development

– Beta feedback on new releases

– Collaborating with our User Interface Designer (who performs site visits)

• To understand your roles (our users)

• To validate our assumptions

– Focused interviews with select customers

More consistent and focused contact with you, our customers



Darwin Information Typing Architecture (DITA)– an XML-based architecture for authoring, producing, and delivering topic-based

technical information– improves searchability, consistency among products, and consumability

Acrolinx IQ– a sophisticated information quality management tool– improves quality and consistency

Editing for quality (EFQ) edits– Improves content quality and consistency

Information architecture standards– Improves usability and consistency

Standardized templates for fix pack and hot fix readmes– Improves usability/readability, and consistency among products

Improved content management system (IDCMS Blue using FileNet)– More secure files (check in / check out)– Infrastructure that supports reuse of topics among product teams

New tools, processes, and standards



Tivoli documentation central

Information centers

IDCMS Blue using FileNet (content management system)

External wikis



A portal to access all Tivoli documentation (organized alphabetically by product)

Maximo Asset Management documentation is located here

Direct URL is: https://www.ibm.com/developerworks/wikis/display/tivolidoccentral/Home

Can also be accessed directly from www.ibm.com

Tivoli documentation central is...

Tivoli Documentation Central



Improved welcome page design

Includes a new 3-tab structure

– Learning

– Tasks

– Community and support

Can include information center tips

Includes links to training and other learning resources

Includes links to various locations

– Discussion spaces (ex: DeveloperWorks forum and Twitter)

– Links to the product pages, wiki, and DeveloperWorks

– Links to user communities

Includes feedback link for your comments

Information centers



Is an internal, second-generation content management system (CMS) for IBM's information development community to use while developing product information

Based on an IBM FileNet product

Re: IBM FileNet??? Yes, we proudly eat our own dog food here...

Is a repository for the source files for active IBM documentation projects

Provides secure check in/check out processes

Enables collaboration

Consolidates information quality management

Provides support for improved– secure storage– navigation and searching capabilities– reuse of DITA topics– cross-product consistency– content integration (removes barriers that created silos)

IDCMS Blue using FileNet (content management system)...



Tivoli Wiki Central includes a growing number of product wikis (Maximo Asset Management, CCMDB, TPM, and others)

About the Maximo Asset Management wiki– URL is https://www.ibm.com/developerworks/wikis/display/maximo/Home– Includes Maximo and all add-ons– Access

• Anyone can view• Those with a developerWorks ID can add/modify community content

– Initial content includes:• A large section on BIRT reports, with overview, administering, and

developing reports• Links to installation tips and tricks• An overview and planning section, with links to the product coexistence and

configuration matrixes• Links to a customer scenario using Maximo and Maximo Mobile• Best practices about escalations and conditional UI• A related resources page for quick links to important sites• A troubleshooting section

External wikis


How you can help

Inform your employees/teams about:– Tivoli documentation central

– Tivoli wiki central and the Maximo Asset Management wiki

– Our redesigned information centers

Actively contribute to the Maximo Asset Management wiki... and give us feedback

Participate in our Agile development teams... and give us feedback

Work with us through a beta program... and give us feedback

Provide your feedback to the Maximo Information Development team through– Maximo Advisory Council meetings

– Talking with Maximo representatives at Pulse

– Online feedback from the information center links

– Contacting one of the ID team leaders

Did I say... “give us feedback?”

Seriously - contact us anytime!


Questions? Comments?

© 2010 ibm corporation maximo documentation: past – present - future andi couilliard 14 january,...

Documents