Read - Do You #WriteRight?
Contents
1. 5 Web app yet use the device capabilities like a native app Web applications can run on many devices but native applications have to be written for specific devices Native applications run faster and can take advantage of device specific capabilities but Web applications cannot Rich media Today s trend is toward tablets and mobile devices with touch sensitive displays that users prefer to traditional pointing devices This makes it natural for users to want to interact visually with information so they appreciate rich media alternatives to text such as animation video 3 D models and hyperlinked parts lists Aberdeen Group found that shrinking budgets and increased workloads are motivating content developers to look for ways to reduce development costs Single sourcing is a documentation methodology that enables you to reuse a modular chunk of information also called an object in multiple documents Creating technical documents efficiently The volume of documents that an enterprise is required to publish will continue to increase Thus the choice is to either increase technical communicators staffing or to increase the efficiency of how the documents are produced The history of manufacturing gives us an analogy In the pre industrial era craftsmen hand made things one at a time No two end products were exactly the same The industrial era increased the rate of production by using identical or similar components for p2. Is widely used has many people trained and has extensive training resources available Has excellent company financials Long term success of your migration to structured authoring depends on choosing an authoring tool from a company that can be relied upon If the selected company doesn t exist in a couple of years your investment would be jeopardized You require your tools provider to Be financially stable and able to ride out recessions Bean experienced leader in the authoring tools segment Stands behind its products for the long term Provides excellent product support 10 RoboHelp gives your enterprise more choices in authoring and publishing especially in its powerful new mobile publishing capabilities in HTMLS The ideal solution Adobe Technical Communication Suite The Adobe Technical Communication Suite TCS is the market leading solution for authoring and publishing technical content in an enterprise TCS s powerful integrated authoring and publishing tools meet all the requirements we have examined Let s examine two major components of TCS Adobe FrameMaker and Adobe RoboHelp Adobe Technical Communication Suite provides just what technical communication pros need in a global mobile always on world What do I like the most In addition to its traditional strengths single source Multichannel XML and DITA publishing Technical Communication Suite 4 cranks it up a notch by providing supp
3. Pringle and O Keefe found that about 12 are evenly split between the DocBook S1000D and non S1000D military standards The remaining organizations use custom solutions or some other standards Some enterprises have information in silos for security purposes so a standard may not be critical Each standard has different strengths DocBook is best for lengthy narratives like training documents but not for mobile or online content which is usually broken into small chunks S1000D is best for aerospace defense and manufacturing which require specific hidden metadata and the ability to maintain an audit trail on document change history DITA can work well for most types of content DITA is powerful but it can be too rigid for enterprises that need extreme flexibility or are not large enough to take advantage of its power DITA supports the concept task and reference template types mentioned previously The ideal structured authoring tool should be able to support any of these XML authoring standards and to support customization for meeting the special needs of customers Momentum for structured authoring and XML remains strong Enterprises are likely to enjoy dramatic savings by migrating to XML if they publish projects containing many pages frequently revise content that is reusable to a high degree or translate projects into multiple languages However XML is not for everyone as it requires a lot of upfront planning and has a sig
4. customer needs If your enterprise generates a lot of content you should consider using an experienced content strategist to lead the development of a unified content strategy A senior content strategist can also determine the best tools for your enterprise and identify additional information types you need such as quizzes and FAQs for your training environment Using a Content Management System Many organizations find that a Content Management System CMS can help them manage large amounts of content productively A good CMS keeps structured content up to date and makes it easy to locate content for reuse and publishing such as filtering XML for publishing into different formats There are different types of CMSs but unless you need a specialized type a component CMS would bea good choice since it manages content at a granular level as compared to the document or page level that most others use A CMS is not an absolute requirement for reuse of content If your analysis determines that a CMS is not right for you your staff should have the technical knowledge to set up content reuse If your analysis determines that a CMS is right for you then verify that the authoring tools you choose integrate well with popular CMSs ideally at no additional cost In authoring the ability to customize the authoring tool to match the role of each contributor cuts the learning curve and training costs dramatically Be careful before committing t
5. for your enterprise A Adobe Adobe Systems Incorporated 345 Park Avenue San Jose CA 95110 2704 USA www adobe com A long term relationship Before you make the commitment to purchase TCS talk with Adobe about having experts work with your enterprise to develop a flexible long term plan for migration from Word The plan should take into account the specific needs of your enterprise including your budget culture tolerance for risk and technical expertise The plan should include long term training needs and where to find the best professional trainers Metrics should be created to test the ROI of each phase before moving to the next Once a plan is in place Adobe can help you plan what software is needed for the first phase For example you may only need a few TCS licenses while your team is being trained to create templates styles and conversions As your staff phases into writing with these new tools Adobe can help you choose the best tools to match your need optimize your expenditures and maximize your ROI Adobe can also work with your team to find certified experts that offer training for specific skills such as how to create templates Training could be live or recorded online or face to face depending on the need Adobe Corporation stands above the rest An authoring tools company should be profitable and have solid financials If not then it may not be around a long time Adobe meets the challenge It had f
6. procedures and reference information 14 Adobe had fiscal 2011 revenues of US 4 216 billion Adobe will be around for the long term and will continue to stand behind its products 3 Migrate content into these templates The content should carefully follow the templates and be written lean minimalist 4 Begin authoring new content into these templates 5 Take enough time to get authors used to the idea of adherence to the structured templates Consider this training for phase 3 6 Verify that the structure is not too restrictive If it is you may need to customize it Phase 3 1 Design a conversion table to your chosen XML standard DITA S1000D DocBook or custom For example if your standard is DITA then variables and insets became CONREFs and conditional text converts into the DITA VAL attributes 2 Convert some documents by hand to your XML standard That way you ll see exactly what is required 3 Convert the rest of your documents You can do it by hand or you can use automation tools built into FrameMaker 4 Your enterprise is now using full XML and can enjoy the efficiency benefits If for some reason you decide that DITA does not suit your needs there is a way to back out Just import DITA project into the FrameMaker project and save it to XHTML Recommendations Test each phase on a small set of content before processing it all Test the ROI using well thought out metrics before moving to t
7. rather than static text and graphics Electronic formats increasing The number of electronic document formats continues to expand beyond traditional formats like PDF files software application help and online help pages New formats include ePub and mobile Mobile growth We ve seen an explosion of Internet ready mobile devices such as tablets smart phones and e book readers Each device has different capabilities and limitations For example e book readers and tablets typically have larger displays than smart phones but smaller displays than desktops To fit smaller displays documents like help files must be broken down into smaller pieces of content The new trend is to create adaptive content that automatically optimizes its appearance to the capabilities of a device Although a carefully designed document converted to PDF may work on a tablet in most cases mobile users will be frustrated zooming and sliding oversized PDFs on small displays HTMLS is becoming the new standard for displaying information because it adapts to the requirements of individual mobile displays It allows us to overcome major incompatibility problems that mobile devices have Mobile content can be displayed as one of three types of mobile device applications Web apps run ina browser and display HTMLS web pages native apps are little programs installed on the device hybrid apps are a combination of the two that allow the app to run on many devices like an HTML
8. Migration from Microsoft Word for Technical Documentation Whitepaper Determining the Highest ROI Solution for Technical Publishing Migration from Microsoft Word Enterprises are motivated Microsoft Word has been around for a long time and is used by over half a billion people to migrate from Word when Enterprises often use it to produce a large percentage of their documents across multiple they realize thatiheiay functions departments since it is known by many people and has a relatively low entry they currently create i i f cost Word is a good text processing tool for writing whitepapers and simple business technical documents is not documents reports but inefficiencies are introduced when technical communicators use it able to keep up with their to create long and complex technical documents like policies and procedures user guides maintenance handbooks and reference manuals with embedded graphics and videos Word was not designed for technical documentation so its total cost of ownership is much higher than if more specialized tools were used For example loss of time due to Word document freeze becomes a daily occurrence as tables and graphics are added growth Enterprises are motivated to migrate from Word when they realize that the way they currently create technical documents is not able to keep up with growth in an enterprise s products and services growth in document t
9. System Using role based tools YES TCS supports detailed styles and layout capabilities YES FrameMaker supports powerful templates that require an author to follow a particular structure when using XML standards You can take the intermediate step of unstructured authoring using modular content designed for reuse and later move to structured authoring with XML YES Conditional text variables and insets make FrameMaker a powerful single source tool I have clients requiring both PDF and online Help output Adobe Technical Communication Suite 4 allows them to single source the content and automatically update all necessary role based outputs from one place Now that Adobe Technical Communication Suite creates HTMLS output my clients can expand their reach to push content to all mobile devices The Help content queries the device and adjusts the delivery based on screen size Matt Sullivan Independent Adobe Certified Instructor Adobe FrameMaker supports single source document production which means only have to write edit and review information once The result is fewer reviewers and writers are needed and translation costs are reduced dramatically Mary Ann Howell Certified FrameMaker Expert YES FrameMaker supports structured authoring and allows a mix of both structured authoring and unstructured authoring No other tool has this capability FrameMaker supports structured authoring in the XML standa
10. echnical communicator can easily import selected changes in place into the FrameMaker source text and manage with track changes Using tools that support publishing and reviewing The PDF round trip function in Adobe FrameMaker 11 has been useful to us with a client project that involves updating dozens of topics every day Rather than send a single PDF of more than 1 000 pages every few days with a request to review specific components we instead send a PDF related to a single topic After client review we import the markup make our edits and resubmit The time for reviews has dropped significantly Bernard Aschwanden President and Owner Publishing Smarter YES FrameMaker is far more stable than Word FrameMaker handles large documents extremely well In fact even the earliest versions of FrameMaker could reliably create and open documents over 1000 pages without crashing It can handle large numbers of graphics in a document without crashing and still have a snappy response time FrameMaker is extremely reliable and maintains file integrity non corruption unlike Word My experience working with lengthy publications proved to me that Adobe FrameMaker has a history of stability that cannot be matched by competing tools like Microsoft Word Adobe FrameMaker 11 allows me to rapidly change the entire structure of a document and its many components without worrying about the document becoming corrupted or incorrec
11. f time to fully evaluate the ROI and determine when and if to continue to the next phase Sample migration plan steps Phase 1 1 2 3 Train lead writers on how to build a template and documenting style guide rules conventions consistently Determine file naming and folder naming conventions for text and graphics usage Train authors on how to use FrameMaker s WYSIWYG editor using the template and naming Import Word documents into FrameMaker From the beginning FrameMaker was designed to work well with Word so importing is smooth If you design the MS Word styles to match your FrameMaker paragraph tags you can import a Word document into FrameMaker and create a clean new FrameMaker document with little cleanup especially if it doesn t have a lot of graphics Begin authoring new content using these templates and naming conventions Customize FrameMaker workspaces so that XML authoring requires only the tools and functionality needed for each role making it easier and cost effective to train FrameMaker users Determine conditional text variable text and insets in order to maximize content reuse and write lean minimalist Phase 2 Determine and test the XML standard that you plan to use in phase 3 DITA S1000D DocBook or 1 custom Create templates that define standard information types similar to your future XML standard For example if you will use DITA define elements for concepts task
12. hased plan for an enterprise that wants to migrate from freestyle Word documents to structured authoring It shows how the tool independent sample migration plan we discussed before can be implemented using FrameMaker RoboHelp and the free Adobe Acrobat Reader Summary Authoring Tools Publishing Tools Reviews Microsoft Word Microsoft Word None Word can generate only print PDF and simple HTML Difficult using Track Changes feature Unstructured authoring using consistent styles and single source FrameMaker in unstructured WYSIWYG mode FrameMaker for print and PDF documents RoboHelp for most online and mobile outputs Free and easy using Adobe Acrobat Reader Mixed unstructured and structured authoring using XML elements for styles and single source FrameMaker in unstructured WYSIWYG mode FrameMaker for print and PDF documents RoboHelp for most online and mobile outputs Free and easy using Adobe Acrobat Reader Structured authoring using XML elements and single source FrameMaker in structured WYSIWYG mode Allows mix of unstructured and structured content FrameMaker for print and PDF documents RoboHelp for most online and mobile outputs Free and easy using Adobe Acrobat Reader Of course your plan should be tailored to your enterprise s specific needs For example your enterprise may be perfectly happy to stay on a particular phase for an extended period o
13. he next phase Enterprises prefer TCS Structured FrameMaker has over 37 of the authoring tools market worldwide with major markets in the US Europe Middle East and Africa Other authoring tools just don t have the same full set of capabilities as TCS For example no other authoring tools support both structured and unstructured authoring Some are missing migration tools a WYSIWYG editor a publishing engine scripting or full DITA support Many have few publishing formats Some tools focus on editing and can t handle the complete authoring cycle Some have exorbitant maintenance contracts Adobe Technical Communication Suite gives us a powerful documentation process from start to finish can author in Adobe FrameMaker and set documents up for review through Adobe Acrobat Using the same set of source files Adobe RoboHelp lets me then publish multiple outputs such as eBooks different types of online help and HTMLS Mary Ann Howell Certified FrameMaker Expert Executives want to have confidence in the software tools company that they choose Unfortunately some tools are made by companies that have not been around very long and or are missing the solid financial numbers that would give us confidence that they are going to exist in the long term It can be a crippling mistake to choose a tool that ends up as a dead product of a failed company 15 Call 206 675 7076 to discuss the highest ROI and lowest TCO solution
14. heading 1 whether a minimum of two bullets in a list is required and rules for images and if image captions are required XML stands for eXtensible Markup Language which means that content is enclosed within tags In XML these tags define an element such as a paragraph an ordered numbered list or unordered bullet list or a heading level With structured authoring and XML content is completely separated from format so a writer can focus on writing and not on appearance This separation allows multiple publishing audiences and delivery formats PDF online mobile to be derived from a single source and increases reuse of topics and modules across product lines The single most important reason why so many companies are considering structured authoring and XML is the ability to future proof documents that need to be delivered on the devices and platforms of the future Ten years ago mobile devices were not thought of as data delivery and Internet connectivity devices Ten years from now current XML standards will provide enterprises with the mechanism for staying current with new technology A good CMS keeps structured content up to date and makes it easy to locate content for reuse and publishing such as filtering XML for publishing into different formats The most commonly used XML content authoring standard is DITA chosen by almost two thirds of organizations that develop structured content Of the remaining organizations
15. hin and amongst document deliverables Using templates to implement document structure efficiencies The requirement of reuse forces writers to think about structuring content within a single deliverable and across multiple deliverables Aberdeen Group found that shrinking budgets and increased workloads are motivating content developers to look for ways to reduce development costs One solution is to reduce the amount of time that authors especially Subject Matter Experts SMEs spend formatting documents SMEs waste a stunning 30 to 75 of their time formatting documents in non structured freestyle authoring tools By using structured authoring to enforce consistency writers don t have to worry about formatting because the styles are applied automatically Structure may be thought of as a pattern Following a pattern provided in structured authoring can speed the creation of content and provide consistent reusable content When users read a technical document they usually have an expectation about the content and its presentation For example when a consumer reads the user manual for a gadget he expects to find the The single most important reason why so many companies are considering structured authoring and XML is to future proof documents table of contents followed by a description of product features and benefits in an overview and finally the sets of step procedures on using the gadget s basic functions If the w
16. ic topics Templates with XML like elements for example DITA like elements for styles Content standards built into templates so authors cannot change them Yes Allows for conditional text variable text and cross referenced linked text Yes by reference to the source file Collaborative authoring using a CMS ora file server Print and PDF documents Online and mobile outputs A good round trip reviewing solution is required Structured authoring using XML elements and single source Structured tools Allow a mix of unstructured and structured content Structured authoring using XML enforced standards DITA S 1000D DocBook or create a custom template Built into templates separated from content so authors cannot change them Yes Allows for conditional text variable text and cross referenced linked text Yes by reference to the source file CMS usually required due to volume of content Print and PDF documents Online and mobile outputs A good round trip reviewing solution is required The Adobe Technical Communication Suite TCS is the market leading solution for authoring and publishing technical content in an enterprise What to look for tools checklist Below is a checklist of features and functionalities that your enterprise could include in your team s search for the ideal content authoring and publishing tools Saves money Has a high ROI anda lo
17. iscal 2011 revenues of US 4 216 billion More than half of Adobe s revenue is generated outside the United States Adobe FrameMaker has an installed base of almost 9000 customers and over 200 000 units sold worldwide As of June 1 2012 Adobe employed approximately 10 474 worldwide Adobe has created world standards such as PDF and Flash and popular tools like Photoshop InDesign and Illustrator Adobe will be around for the long term and will continue to stand behind its products TCS has the highest ROI of other authoring tools Adobe developed a simple ROI CALCULATOR that will give you an idea of the efficiencies your enterprise could enjoy by migrating to TCS Try it here You can t afford to make a mistake in choosing the ideal authoring and publishing tools for your enterprise technical documentation Call 206 675 7076 to discuss the highest ROI and lowest TCO solution for your enterprise 1 Adobe Technical Communication Suite Aberdeen Whitepaper The Technical Communicator s Transformation Publishing On Time and On Quality by David Houlihan 2 Alan S Pringle and Sarah S O Keefe 2011 The State of Structured Authoring Scriptorium 3 Rockley Ann Cooper Charles 2012 Managing Enterprise Content A Unified Content Strategy 2nd Edition New Rider Subject to Apple s current requirements and approval Adobe the Adobe logo Acrobat FrameMaker and RoboHelp are either registered trademarks or trademarks of Adobe S
18. ly so small Enterprises need a professional set of tools specifically designed for efficient technical documentation authoring and publishing Requirements for successful migration from Word There are certain requirements that all enterprises demand for a successful migration no matter what tools or methodologies they choose The migration must take into account the culture of the company including its tolerance for change and risk Otherwise the migration will be too disruptive A long term plan is vital to success since it lowers costs by reducing surprises To reduce the chance of hidden costs popping up the plan should include The cost of technical documentation you create today The cost of technical documentation you plan to create The long term training needs of your staff The consulting needed for technical issues and guidance A tools analysis and cost estimate Jumping to structured documents immediately is often too big of a leap so your authoring tools should allow for a gradual migration That means the solution must allow for a mix of unstructured and structured documents To reduce risk Use a small team to migrate a portion of your documents at each stage use metrics to measure the effort Follow a plan thatallows future phases to change direction based on what happens in the current phase There is no one size fits all way to migrate from Word Apply a solution that allows your enterprise to p
19. need to have the right tools for conducting documentation reviews and review comments should lend themselves to easy aggregation filtering and incorporation Using tools that support publishing and reviewing In addition to the authoring issues we have examined enterprises need powerful publishing and reviewing capabilities This is where many tools fall short The tools must be able to publish to all the required outputs such as print PDF documents online and mobile outputs The tools must also support a full reviewing cycle where documents can easily be sent to reviewers reviewers can easily make changes and their comments can be easily incorporated Using dependable tools Enterprises demand high levels of dependability in the tools that they use for authoring and publishing technical documentation regardless of the size of the document the amount of content it contains or the type of content Service and support are essential in large enterprises and a large pool of certified professionals for training writing consulting and template design needs to be available Using industry standard tools Enterprises need access to a large pool of skilled writers so they need tools that are popular credible and well established Since no enterprise wants to invest in tools that become orphaned the tools company should be reputable and have solid financials Microsoft Word evaluation Efficiency methodologies support Word only support
20. ngle sourcing with modular content Single sourcing is a documentation methodology that enables you to reuse a modular chunk of information also called an object in multiple documents First you build objects such as procedures and tables and put them in source files Then you organize them into documents such as manuals and websites Finally you link them together into cross references such as tables of contents and indexes If you change an object it automatically changes in all the other documents that reference it Compare this method to the traditional copy paste which can be a nightmare to maintain There are several money saving advantages to single sourcing Reduced translation costs since chunks of text are reused and therefore not retranslated This can be a major cost saving in enterprises that have more than one language to translate to Increased consistency of information presented Reduced development and maintenance costs and shorter time to market efficiencies Rapid reconfiguration since small content modules can be rearranged to create something new Using structured authoring and XML Using structured authoring and XML can be thought of as authoring with templates on steroids The content rules are defined and embedded in the DTD Document Type Definition file and are rigidly enforced and validated by the software the author is using For example content rules define what type of information should follow a
21. nificant startup cost and learning curve Organizations with a small documentation set and a simple publishing matrix may not have a sufficient ROI if they move to XML There has been a tendency to rush some organizations into using structured authoring and XML just because it is trendy Before committing to migration to XML enterprises should learn what it is what are the risks and the migration costs An ideal approach would be a pilot project to determine which XML standard if any is most suitable The pilot would migrate a small portion of the documents and use carefully thought out metrics to measure ROI The pilot experience might change the XML standard the enterprise decides to use For example DITA can be used in many industries but its roots are software documentation and due to recent improvements training documentation If the pilot program were to test DITA and determine it is too rigid a custom XML structure or some other solution could be considered For some small enterprises the pilot project may result in only using single source methodologies developing modular content and following written standards and writing styles Using a unified content strategy Ann Rockley and Charles Cooper describe a unified content strategy as a repeatable method of identifying all content requirements up front creating consistently structured content for reuse and managing it in a definitive source and assembling content on demand to meet
22. o a CMS There is a high failure rate often due to unrealistic expectations and insufficient planning CMSs have a higher success in enterprises with many documents many complex documents or many writers CMSs range widely in power and cost so your analysis should carefully determine the best solution There are open source options that you can use in your test phase to see if a CMS is the right choice Using roles based tools Customization is vital In an assembly line the tools that a worker uses are exactly matched to the need of that station In authoring the ability to customize the authoring tool to match the role of each contributor cuts the learning curve and training costs dramatically Not everyone needs to be trained on every aspect of document creation and delivery and not everyone needs every single tool with every feature activated Roles might include technical communicator SME author publisher and content manager Each requires very different capabilities from the tools For example an SME author would need to fill out a template and review documents whereas a technical communicator may need to create templates author and incorporate reviewer edits In addition to the technical communicator tools a publisher would need to have additional tools to deliver content to the media output required whether ePub PDF HTMLS or XML and support the required platforms including tablets and various mobile devices All reviewers would
23. ort for multiscreen HTMLS output Now you can preview mobile optimized technical documentation content destined for smartphones eReaders tablet computers and other mobile devices from within familiar authoring interfaces Kudos Adobe Scott Abel The Content Wrangler Inc Read more product reviews FrameMaker FrameMaker supports the entire content authoring and publishing cycle Whereas most authoring tools require that you jump fully from unstructured to structured authoring FrameMaker is the only tool in the market that allows legacy unstructured documents to exist along with structured XML documents This allows your enterprise to choose any level of structured authoring at each step of your migration plan Adobe FrameMaker 11 is stronger faster and smarter Authoring and publishing for today s cutting edge technical writer is about to get a whole lot better My favorite features include Smart Paste an editable XML view and a host of new keyboard shortcuts Jacquie Samuels Writer TechWhirl com Read more product reviews RoboHelp No matter what authoring tools your technical communicators are using it makes sense to switch to tools optimized for online authoring that can also output hardcopy and mobile RoboHelp is a leap forward in publishing Previous versions have been great at authoring and publishing online content but now RoboHelp gives your enterprise more choices in authoring and publishing e
24. ranslation and growth in publishing formats beyond traditional print and PDF such as ePub tablets smart phones desktop HTML and other online formats This whitepaper presents Factors that drive the cost of technical document creation Methodologies that can increase operational efficiency in technical publishing Whether Word can implement the desired methodologies and achieve sufficient dependability in technical publishing projects The reasons for the Total Cost of Ownership TCO to create technical documentation using Word being more expensive than expected Word dependability pain points experienced by your technical communicators The requisites for a successful migration from Word to another authoring and publishing tool for technical publishing projects A list of desired attributes for ideal authoring and publishing tools for technical documentation A specific solution that has a higher Return on Investment ROI than Word in technical documentation projects and allows an enterprise to get products and services to market much faster at a lower cost thereby increasing an enterprise s overall profitability and efficiency As an enterprise increases the variety of products and services it offers additional technical documentation is needed The choice for enterprises is to either increase technical communicators staffing or to increase the efficiency of how the documents are produced What drives
25. rds of DITA S1000D DocBook or custom XML YES FrameMaker integrates with many popular CMSs some of which are included for free YES FrameMaker can be customized for the role of each contributor decreasing the learning curve Not all technical authors are the same That s why it s hard to select a single authoring tool that meets the needs of each and every contributor FrameMaker 11 acknowledges this problem and provides a much needed solution in its new role based views approach Customizable authoring experiences XML Code View for power using code junkies Author View for writers and WYSIWYG view for those who need a simple desktop publishing esque view of the content being produced provide a much needed addition to the professional technical communication tool arsenal Scott Abel The Content Wrangler Inc 12 YES FrameMaker has historically had its strength in creating print and PDF documents but RoboHelp moves it up several notches with cutting edge online and mobile outputs A real bonus is the smooth workflow between Adobe FrameMaker 11 to Adobe RoboHelp 10 within Adobe Technical Communication Suite 4 Here you have a toolbox 7 of the best of breed apps for technical writers John Daigle President and Owner Evergreen Online Learning LLC TCS has powerful reviewing features Technical communicators can send PDFs to reviewers who can use the free Adobe Acrobat Reader to edit the PDF The t
26. riter has decided to remove the table of contents and document the steps in the form of paragraphs it would make it difficult for the consumer to find and use the information because the expectation of a logical order and appearance is unfulfilled Standardized templates ensure a consistent structure and style The requirement of reuse forces writers to think about content module types Template standards typically include modules like Concept modules paragraphs of information that describe an idea answering the question What is Task modules step by step description to accomplish something answering the question How dol Reference modules reference information that you look up rather than memorize such as tables and lists Technical communicators often gather information from SMEs by giving them a template to fill out For example a task template to document a procedure may contain the name and purpose of the procedure introductory information and the task steps Once the SME fills out the template and returns it the technical communicator edits and refines the writing By having all writers use the same templates the overall structure of the document should be consistent The reality is that templates are difficult to enforce if authoring tools are not chosen carefully For example if templates are set up in Microsoft Word writers and SMEs can still change the structure and the paragraph styles Using si
27. roducts in the same family of products lowered manufacturing cost and ensured a more consistent quality Following that analogy into the documentation environment we have three basic inter related concepts to implement before you can start to achieve document manufacturing efficiencies Consistency of document look and feel tone structure and writing style format standards Reuse of content Specialization of tools to fit the role Most technical writers are creative which is a positive attribute unless it results in the creation of inconsistently formatted content or delivery of information not in the sequence that the reader may expect For example multiple writers usually work together to create a large document but if each of them writes as per their respective styles the reader will notice that the document doesn t have a consistent tone style or structure which can result in a negative quality perception about the product and the company or a call to customer support if the document is confusing Reuse of content requires writers to think creatively about how to repurpose content and how to write reusable content modules For example if the steps for installing a piece of software are identical for all products in a hardware product family then the writer can reuse the entire task module to describe the installation for each product s documentation set The writer may also reuse the content a
28. rofit from efficiencies immediately The ideal content authoring and publishing tools must have a number of features and functionalities Tool independent sample migration plan Here is a sample multi phased plan for migration from Word to structured authoring Summary Authoring Tools Authoring Structured unstructured Styles Single source Content reuse Content management Publishing Tools Reviews Microsoft Word Microsoft Word Unstructured Standard styles difficult to enforce Copy paste CMS is not supported None Word can generate only print PDF and simple HTML Difficult using Track Changes feature Unstructured authoring using consistent styles and single source Unstructured tools Unstructured authoring Modular lean minimalistic topics Unstructured templates Consistent styles and standards that must be manually enforced Yes Allows for conditional text variable text and cross referenced linked text Yes by reference to the source file Collaborative authoring using a CMS or a file server Print and PDF documents Online and mobile outputs A good round trip reviewing solution is required Mixed unstructured and structured authoring using XML elements for styles and single source Unstructured and structured tools Allow a mix of unstructured and structured content Structured authoring concepts Modular lean minimalist
29. s unstructured authoring and it In our final analysis does Microsoft Word support the efficiency methodologies we discussed that enterprises require for technical documentation Let s look at a summary of our analysis does not support a mix of unstructured and structured documents Microsoft created Word as a mass market easy to use text processing product for everyday business use Using format and writing style guidelines Using templates Using single sourcing with modular content Using structured authoring and XML Using a Content Management System Using role based tools Using tools that support publishing and reviewing Using dependable tools NO Word allows styles but it has no mechanism to enforce content writing style and prevent the author from changing the formatting styles or using the ribbon menu to make style changes NO It is possible to compose a template for authors to fill out but Word has no mechanism to prevent the author from changing the styles and the structure of template Over time a template with no means of enforcement will fail Ideally the tools must be able to separate style from content and enforce the structure rules NO Word lets you include pieces of content but it does not have the mechanisms built into it to allow enterprise level reuse and single source For example Word cannot use the single source technique of conditional text or an easy way to reuse variables in
30. s part of a training video script to be deployed on YouTube as a distance learning module or as a reusable learning module for instructor student training guides Let s examine specific efficiency methodologies that address both style and reuse and some of the challenges enterprises face in achieving them Using format and writing style guidelines An enterprise can reduce document creation costs by creating style and writing standards defining the appearance of documents These styles ensure a consistent look and feel incorporate company branding into all the document deliverables by using a standard company logo and consistent color palette as well as corporate terminology usage Formatting involves establishing paragraph styles for headings Headings 1 2 and 3 and body content Normal indent bullets and numbering and then applying the appropriate style to each paragraph Traditionally writers follow a style guide that defines an enterprise s standards for editing and formatting where a person acting as an editor is responsible for ensuring that writers follow the style guide Unfortunately today s constrained resources often require the technical writers authors and communicators to be their own editors Given the large number of styles in a typical style guide this can be problematic Also since each author has a different style of writing the lack of an independent editorial review often leads to inconsistencies wit
31. single to multi column still require insertion of section breaks which can corrupt adjacent numbered headlines Long multipage tables with a graphic in every row are almost guaranteed to make a Word file crash Editing equations corrupts layout Word wasn t built to handle the methodologies that enterprises need for efficient creation of technical documentation Jumping to structured documents immediately is often too big of a leap so your authoring tools should allow for a gradual migration Conclusion Word wasn t built to handle the methodologies that enterprises need for efficient creation of technical documentation Some organizations have tried to force Word into enterprise level methodologies by adding plug ins and proprietary macros Just as a trucking company would never try to turn a car into a truck because they were designed for fundamentally different purposes eventually enterprises realize that no matter how much it is modified Word was never intended to meet demanding high volume technical documentation methodology requirements on an enterprise scale Microsoft created Word as a mass market easy to use text processing product for everyday business use That market is huge in comparison to the market for technical document authoring and publishing tools The hard truth is that Microsoft isn t focused on your enterprise s technical documentation productivity issues because that market is comparative
32. specially in its powerful new mobile publishing capabilities in HTMLS which is the de facto mobile standard FrameMaker users can author in FrameMaker and import or link a file into RoboHelp to take advantage of RoboHelp s specialty in online publishing such as HTML 5 multi screen display RoboHelp can generate hybrid apps for publishing to mobile devices and can also generate native apps for the iPhone and Android The mobile features that Adobe has included in Adobe RoboHelp 10 mark a tremendous leap forward into one of the hottest new areas in technology for technical communication Neil Perlin President Hyper Word Services Read more product reviews 11 Now that Adobe Technical Communication Suite creates HTMLS output my clients can expand their reach to push content to all mobile devices Matt Sullivan Independent Adobe Certified Instructor FrameMaker has historically had its strength in creating print and PDF documents but RoboHelp moves it up several notches with cutting edge online and mobile outputs TCS efficiency methodologies support Let s evaluate whether or not TCS can support the efficiency methodologies that enterprises require for technical documentation and see opinions by industry leaders about TCS Using format and writing style guidelines Using templates Using single sourcing with modular content Using structured authoring and XML Using a Content Management
33. text files or to manage linked text inserts when using a server environment Without reuse duplicate text will be translated which can be costly NO Word only supports unstructured authoring and it does not support a mix of unstructured and structured documents Word does not allow straightforward authoring in XML Although its internal structure is XML it is proprietary and exports to a flat XML text file that is not easily used or transformed into something usable NO Word cannot interface with CMSs NO Word cannot be customized for the role of each contributor NO It is difficult to convert Word documents into multiple types of output such as web help or mobile content It lacks features like clean and efficient automation of table of contents indices and cross references needed by technical communicators and publishing skins for various output media such as ePub and mobile Reviews in Word from multiple people are difficult to integrate and the reviewers must own Word Unfortunately Word can be undependable in the following common technical document situations Long documents are known to increase the chance of crashing Word or corrupting the document especially if a computer is low on memory or if a document has several heavy graphics and tables Graphics tend to shift around unpredictably in large documents Word has problems generating table contents and index in large documents Changes in page layout
34. the cost of technical document creation One of the largest cost factors in document creation is labor The amount of labor performed by technical communicators is based upon the volume of documents that must be written the number of writers available and their efficiency If the volume of documents is too great then it s necessary to defer the work increase the number of writers or the efficiency Current trends that increase the volume of documents A number of factors can increase the volume of documents that an enterprise must produce Growth in products and services As an enterprise increases the variety of products and services it offers additional technical documentation is needed Global growth Customers around the world expect technical documentation to be translated to their language and culture Paper documents replaced by digital content Traditional papers for technical documents are rapidly being replaced by digital content because paper can be inconvenient to carry expensive to distribute and difficult to search for answers Users want the smallest amount of information that will solve their need in an easily consumable and immediately actionable format Interactivity Today s customer wants to give real time feedback on digital content such as reporting errors in documentation and contributing new content This requires new in built mechanisms Also users demand that content to dynamic and interactive in nature
35. tly published Also impressive is that FrameMaker correctly generates a variety of content across page spans including indexes tables figures headings cross references equations and multiple paragraph and character level styles Using dependable tools Bernard Aschwanden President and Owner Publishing Smarter Powerful automation tools available Adobe created powerful server automation tools that decrease publishing costs and are specifically targeted towards the efficiency requirements of enterprises Adobe FrameMaker Publishing Server is an enterprise software for automated multichannel publishing Access publishing services remotely and manage it with a comprehensive dashboard Easily generate HTMLS output for multiple devices Publish to EPUB 3 KF8 MOBI PDF mobile apps WebHelp CHM and more formats Leverage out of the box support for Adobe Experience Manager EMC Documentum and Microsoft SharePoint or use the new web APIs to smoothly integrate with other CMSs Adobe RoboHelp Server software extends the managing and tracking capabilities of Adobe RoboHelp software Automatically build multiple sections of a project and then publish as a unified online information system 13 Your migration plan should be tailored to your enterprise s specific needs TCS is the only authoring tool that supports both structured and unstructured authoring TCS sample migration plan Below is a hypothetical multi p
36. w TCO Supports content reuse and single source Can communicate out of the box with popular CMSs at no additional cost Ease of use Has a WYSIWYG editor Has the ability to customize workspace for role based publishing so that only the tools required for staff and project goals are present Can easily break large documents into reusable pieces Styles Can define a standard set of styles Automatically creates style sheets from existing unstructured documents Understands how to manage and integrate the style sheets with the content Should automatically enforce consistent writing such as text automatically formatting as a user fills in the blanks Structure Allows a mix of structured and unstructured documents which enables migration to be done in phases Can separate a document s appearance from its structure Supports XML authoring standards such as DITA but allows for any level of customization Templates Can create templates of content structure for authors to fill out Publishing Can publish information in many formats such as print PDF online and mobile Easily integrates rich media into content Can import Word and other legacy documents Supports the full development cycle Can handle the full content development cycle efficiently including publishing translation and reviews Gathers and integrates feedback from reviewers and users Established
37. ystems Incorporated in the United States and or other countries All other trademarks are the property of their respective owners 2015 Adobe Systems Incorporated All rights reserved Printed in the USA 5 15
Download Pdf Manuals
Related Search