The story of where we started, what we bought, and what we are learning as we move from structured FrameMaker using DocBook to Arbortext Editor using DITA.
6. Tools and Workflows (cont.)
@LavaCon
Content Type Tools Process
Software
• NiagaraAX-3.x •FrameMaker 7.2, 8, 9, 10
•DocBook stylesheets (docbook-xsl-1.71.1 customized)
•Saxon processor
•Custom xsl processing as part of the s/w build
•DITA OT (another rig?)
FM > XML > HTML
• Appliance Guides •FrameMaker
•WebWorks
•InsetPlus (FM plugin)
•AXCM (FM plugin)
FM > HTML
• Other (Developer) •Word, Acrobat Pro
•Dreamweaver (CSS &HTML editing)
•Acrobat Pro
•Word > PDF
•HTML >PDF
Hardware
• Installation Guides •FM-7.2 FM > PDF
M
7. 1.2 What we realized
• Problems ahead
– More Writers
– Mixed Toolsets
– Mixed Processes
• Justification for change
– Avoid disaster
– Take advantage of new technologies (DITA)
– Increase productivity
– Scalable for future growth
@LavaCon
M
8. 1.3 What we planned
• New Tech Pubs processes
– Make DITA the Tridium standard
– Move to task-based documentation
– Learn to use minimalism principles
– Content inventory and analysis
• New Tech Pubs tools
– Standardized
– Scalable
– DITA compatible
@LavaCon
M
9. 1.4 What we needed
• Education and training
– Make DITA the Tridium standard
– Move to task-based documentation
– Learn to use minimalism principles
• Help from an expert(s)
– Choosing tools
– Installing and configuring CCMS
– Performing content inventory and analysis
• Meet ongoing documentation deadlines
@LavaCon
M
10. 2 HOW WE STARTED
After years of dreaming…
@LavaCon
J
11. 2.1 What we purchased
• Mentoring from Single Sourcing Solutions
– Purchasing, spec’ing process
– Installation
– “Jump Start” process
• Arbortext Tools from PTC
– Arbortext Editor
– Arbortext Styler
– Arbortext Publishing Engine
– Arbortext Content Manager
• Arbortext eLearning Library
@LavaCon
M
12. 2.2 Building on experience
• We already know “structured”
– DITA “Topics” similar to DocBook <Sections>
– DITA “Tasks” are like DocBook <Procedures>
• DITA is different but draw on familiar
concepts
– XML markup
– Non XML markup (format catalogs/styles)
• FM users and styles
• Word users and styles
@LavaCon
M
14. 2.3 Content analysis
• Driver docs
• Met weekly with mentors
• Content analysis
• Task analysis
• Results
– Reuse potential
– Standardized topic list
@LavaCon
J
15. 2.4 Tech Doc Standards
• Style Sheet development
– DITA tagging and highlighting guide
– DITA style guide
• Code review
• Process review
@LavaCon
M
16. 3 WHAT WE’RE LEARNING
On the road to DITA…
@LavaCon
J
17. 3.1 Adapting to DITA
Environment
• File explosion uneasiness
• One FrameMaker Chapter
is now “many” files
@LavaCon
M
18. 3.1 Adapting (continued)
• Tool helps and hindrances
• Trusting CCMS not file naming conventions
• Configure CCMS to help with your workflow
• Possible tool confusion with new interface and tool
legacy terminology (not for writers)
• DITA helps and hindrances
• DITA Maps can help
• DITA Maps can hurt
• Learn how to use your new tools – discuss
with the group regularly
@LavaCon
M
19. 3.1 Adapting continued
• Getting good at searching your content
– Understand DITA metadata features
– Standardize, “use a taxonomy”
• Learn as you go, not in isolation
– eLearning and working
– Refer to your Style Guides
– Refer to reference books
– Refer to peers – discuss
@LavaCon
M
20. 3.2 Content
• Have a strategy for legacy content
• Know your subject
• Standardize topic/book outline
– One task per topic; no subtasks
– Install, configure, test
• Develop consistent naming conventions
• Use throw-away DITAmaps
@LavaCon
J
21. 3.3 Content challenges
• Remain task oriented when documenting
features
• Some features don’t need doc!
@LavaCon
J
22. 3.3 Standards
• Communicate and compromise
– Writing style and element (tag) usage
– Process
– Content (reuse opportunities)
• Review markup and usage
– Consistent markup enables reuse
– Taking advantage of reuse opportunities
@LavaCon
M
23. 3.4 Get help
• Use examples to learn to think DITA
• Use the experts
– Consultants
– Forums
• Documentation and Technical Writing
Management
@LavaCon
M
24. 3.4 Get help continued
• Read books and refer to them often!
@LavaCon
M
26. 4.1 Align docs with agile
• Topics become part of Sprint planning
• Reviews become smaller “sprint-friendly”
• Engineers are more aware of content
development and review
@LavaCon
M
27. 4.2 Implement doc life cycle
• Take advantage of the CCMS
– Workflow
– Status
– Baselining
– Revisioning and archiving
• Adapt agile tools (JIRA) to documentation
process
@LavaCon
M
28. 4.3 Alternate content delivery
• Make content available everywhere
• Support product branding
• Translation
@LavaCon
M
29. 4.4 Comfort level
@LavaCon
J
• DocBook works in Arbortext Editor
• We can get our work done while
implementing the new system
• Our comfort level is growing
30. 5 THE BIGGIES AND
FREEBIES
We hope you take away…
@LavaCon
31. 5.1 The biggies
• Power of analysis
• Mindset shift
– Use examples
– Talk to each other
• Get good help
– Single Sourcing Solutions
• Stay the course
@LavaCon
J M
32. 5.2 Freebies
• Content analysis spreadsheet
• Task analysis interview outline
• Links to our best books
• A collection of other useful links
Email: Julie Atkins
@LavaCon
M
Hinweis der Redaktion
Mike
Long time Technical Writer
In this implementation I have served as the database architect and technical resource for the rest of the team.
Julie
Sr. technical writer and independent consultant – over 30 years experience
Unstructured word, Ventura Publisher, FrameMaker
Personal DITA user and enthusiast
Got the mechanics, working on making reuse possible
Although I am a consultant coming in from the outside with some DITA experience, I have been working as a writer team member and an advocate for all things DITA.
We’re telling our story. We’re not there yet, but we’ve made great progress and trust that something we say will encourage you with practical experience and advice on your journey. If you have questions, please make a note and we will leave time at the end to engage your questions.
We want to give you a snapshot of our deliverable process, why we could see that something needed to change and our wish list.
Tools
* Began to “structure with FM-7.1 using free tools and DocBook, self-learning from books, workbooks, online Forums, & FM-Plugins.
Advanced to Structured FrameMaker (7.2, 9, 10) all tricked out with plugins for “conrefs” and “insets”
DocBook:
DocBook stylesheets (xsl), Saxon processor, Ant (see the whole list in Joanne Hackos DITA book)
WebWorks (standard edition)
DITA:
DITA-FMx, InsetPlus and other West Street Consulting tools, Archiving tool, Mif2Go
WebWorks (standard edition)
Workflows:
* Fm > xml
The significance of this list is not simply recognizing the confusion and file sharing limitations imposed by the different toolsets. It is realizing the amount of support is required for setting up the tools and maintaining a suffiicient level of expertise with the tool so that you can troubleshoot and make changes as necessary over the years. This is especially hard if you don’t tweak them that often.
Justification for changing and purchasing toolsets and processes
Processes required a checklist
Tools are fairly difficult to setup and maintain
Each writer needs to maintain required toolset and follow the process using the checklist. Hard to setup new writers.
Talk about metrics here: Time consuming.
Standardized tools that are:
* sustainable
* scalable with growth
I know that some people are using files systems or non-cms based tools to support DITA.
For me that was not an attractive option.
We have spent years analyzing our situation and attending conferences. Just as a practical matter, we think you would like to know what we bought, how we have leveraged our experience to change our ways of doing things, how we analyzed our content, and how we prepared to build our style sheets.
SSS Worked with us through the specification and purchasing process to help us buy the software that we needed and not buy what we didn’t need.
Some sales people may sell the software but they really don’t know the software.
Needs vary by organization
Building on experience
We started with Structured Authoring and DocBook. "Book Structure" was an easier introduction to Structured Writing than DITA but provided to be a great intro into XML and structured authoring in general. We'd been doing that for 5 years or more. This also provided experience with the structured authoring tools...
Using docbook, we’ve been writing in “topics” for years.
While not perfect, they do give us a great transition point for moving to DITA concepts, references, and tasks.
Content analysis
We followed analyzed a subset of our doc library (driver documents), finding opportunities for shared content.
We got a sample analysis spreadsheet from our Mentors and adapted it.
The result of the analysis step was a list of topics that seemed to be standard for all drivers. Just as it is important to standardize your use of elements, it helps (for reuse) to standardize your outline.
One of us took the new list of topics and applied them to writing a new driver guide.
Each week we met with our mentors and discussed the experience and what we were learning.
Results
Standardize outline: Topic
Book
Stylesheet building process
Stylesheets, process documentation references, and examples available for Writers as they use new tools and methods. (we are using a Confluence Site and Windchill folder to hold these docs).
DITA tagging and highlighting guide
DITA style guide
We are learning things about our new tools, and about how to work with content as we move toward a full DITA implementation. We are learning the importance of standards and how to enforce them. And we recognize the need for help from our external consultants.
Writers want to control file naming, as in the past.
Setup automatic naming rules and forget it.
bnaming theLOOK FOR FILE STRUCTURE that Julie created on the network for her dita work
Working in our "legacy" FrameMaker environment, all files are stored on a local hard drive and backed up to a network drive or on our Portal. This issue was addressed (not "solved") immediately by installing and learning to use a CCMS.
Working with a CMS was a bit confusing at first:
Difference between an XML editor and a CMMS repository database. Need to understand the new model of storing in database versus filesystem.
While the structure of the content stored in the CMS appeared to be similar to a familiar HDD file structure, a major difference is the concept of a container that is separate from the document. This confusion demonstrated itself when we created a topic, then wanted to change the name of the topic file. A CMS provides a history of the topic life cycle. Containers can include metadata. It became clear that we have a whole new way to look at data.
Writers want to control file naming, as in the past.
Setup automatic naming rules and forget it.
Working in our "legacy" FrameMaker environment, all files are stored on a local hard drive and backed up to a network drive or on our Portal. This issue was addressed (not "solved") immediately by installing and learning to use a CCMS.
Working with a CMS was a bit confusing at first:
Difference between an XML editor and a CMMS repository database. Need to understand the new model of storing in database versus filesystem.
While the structure of the content stored in the CMS appeared to be similar to a familiar HDD file structure, a major difference is the concept of a container that is separate from the document. This confusion demonstrated itself when we created a topic, then wanted to change the name of the topic file. A CMS provides a history of the topic life cycle. Containers can include metadata. It became clear that we have a whole new way to look at data.
Getting good at searching your content
Understand DITA metadata features
Standardize, “use a taxonomy”
Try to learn as you go, not in isoloation
eLearning and working
Refer to your Style Guides
Refer to reference books
Refer to peers – discuss
Remember your goals: Establish one source of the truth (but don’t force uniformity)
Collaboration has to be easy
Writers have to be able to iterate
Multiple deliverables must be easy to create
Review by topic must be easy
Topic maintenance must be easy
Communicate and compromise
Know what you’re standards are. Talk about them, change them if needed.
Example: “dialog box” vs. “dialog”
Make sure everyone is using the same process.
Identify and share reuse possibilities (task analysis, documentation plan identifies)
Review markup
Consistent usage
Use of tags <shortdesc>, <prereq>, task wording, such as use of gerund.
Example: “Definition List” vs <ul>
Document how you do it and check that you doing how you documented it.
Look at examples from other DITA docs
Mentoring
Forums and other Social Media
Many company product development processes are changing. We need to change with them. Our tools possess capabilities that we have explored but not implemented yet. The possibilities seem endless. Beyond the constant striving for more, we seek to reach a comfort zone where we won’t be constantly implementing new stuff.
Mobile access
Web access
What we've developed as "strategies for authoring in DITA"
What we're using to help take advantage of the reuse potential of DITA
What processess (new and old) that we're using to work with DITA authoring
We want you to take home some specific ideas that we trust will help you. We would also like to make available some specific resources.
Never ends. Each project, always doing it.
Mindshift
Task orientation
Book to topic
Stay the course
provide context and acknowledge both problems and success
Give us your business card if you would like a ZIP emailed to you with the following: