DITA Workflow 101- An Action Plan for DITA Implementation
•Als PPTX, PDF herunterladen•
1 gefällt mir•356 views
Understanding the value of Darwin Information Typing Architecture (DITA) is easy, but the DITA adoption process can be very overwhelming for some. Implementing the DITA standard is not easy by any means, but if carefully planned and executed the adoption process will go much smoother. The DITA Workflow 101 will cover the basic steps you need to follow in order to succeed in your DITA implementation efforts. Topics included will be Data Analysis, Architecture Strategy Development, Technology Evaluation, Training, Conversion, Authoring, Style Sheet development and Output/Publish.
Empfohlen
Empfohlen
Weitere ähnliche Inhalte
Andere mochten auch
Andere mochten auch (19)
Ähnlich wie DITA Workflow 101- An Action Plan for DITA Implementation
Ähnlich wie DITA Workflow 101- An Action Plan for DITA Implementation (20)
Kürzlich hochgeladen
Kürzlich hochgeladen (20)
DITA Workflow 101- An Action Plan for DITA Implementation
- 2. • Founded in 1973 in San Antonio, TX • A Vast experience in all types of XML-based authoring and conversion (SGML, XML, DITA, S1000D) • Over 10 years experience helping companies integrate the DITA standard • Equipped with the resources to tackle a project of any size from beginning to end
- 3. Today’s Speakers Joe Storbeck Senior Structured Data Analyst Joe has been working closely with the DITA specification since its release at IBM in 2001, and is a highly regarded expert in its use and application. Matthew Cassi Account Executive - DITA Account Executive at JANA, Inc. with a focus on structured data methodologies (DITA, S1000D) and the content management industry and communities.
- 4. The DITA Source Joe Storbeck’s DITA Source blog: http://www.janacorp.com/blog
- 5. Agenda Definition of Team Member Roles DITA Workflow 101 Q&A Closing
- 6. TEAM ROLES
- 7. • Editor • Author • Tech Tools Guru Team Roles & Responsibilities • Information Architect
- 8. DITA Implementation Roadmap Data Analysis Conversion & Authoring Effort Style Sheet Development Final Deliverables Architecture Strategy Development Training Technology Evaluation & Selection
- 9. Data Analysis Conversion & Authoring Effort Style Sheet Development Final Deliverables Architecture Strategy Development Training Technology Evaluation & Selection Data Analysis
- 10. Example of questions to ask for a successful DITA implementation: • Is the source material in a different structured language, or are you converting from a desktop publisher? • Is your source data consistent, or even well-organized? • With your content in its present form, is it even possible to categorize the data into the various topic type options? Data Analysis
- 11. Architecture Strategy Development Data Analysis Conversion & Authoring Effort Style Sheet Development Final Deliverables Training Technology Evaluation & Selection Architecture Strategy Development
- 12. • How are you going to move existing data into the various elements? • What are you going to move? • How are you going to repurpose existing DITA elements to fit your needs - while always trying to stay within the framework of the DITA standard? • How are you going to identify material that can be reused? • What will your file directory look like? Architecture Strategy Development
- 13. Technology Evaluation & Selection Data Analysis Conversion & Authoring Effort Style Sheet Development Final Deliverables Training Architecture Strategy Development Technology Evaluation & Selection
- 14. • Take the time to understand your data and how it fits into your overall architecture strategies • Use the information that you gather to choose the right authoring software and/or CMS for your organization • The CMS can be the most critical decision you make. Don’t rush it!! Technology Evaluation & Selection
- 15. Training Data Analysis Conversion & Authoring Effort Style Sheet Development Final Deliverables Architecture Strategy Development Training Technology Evaluation & Selection
- 16. • Give your editor or tools support person the training task • Provide training as close to the beginning of the conversion process as possible. • Don’t throw DITA at your staff and hope for the best. Training
- 17. You may need to convince writers that topic-based writing works. Show them the DITA difference. Training
- 18. Data Analysis Architecture Strategy Development Technology Evaluation & Selection Conversion & Authoring Effort Training Style Sheet Development Conversion & Authoring Effort Final Deliverables
- 19. Conversion & Authoring Effort • Clean up tags • Create a topic- based outline • Look for duplicate information • Fix and formatting problems • Fix broken links • Verify topics have been typed correctly Before After
- 20. Data Analysis Architecture Strategy Development Technology Evaluation & Selection Training Conversion & Authoring Effort Style Sheet Development Final Deliverables Style Sheet Development
- 21. • Purpose • Languages • Processing Tools Style Sheet Development
- 22. Data Analysis Technology Evaluation & Selection Training Conversion & Authoring Effort Style Sheet Development Architecture Strategy Development Final Deliverables Final Deliverables
- 23. Final Deliverables Standard Profiling Attributes • Audience • Platform • Product • Props • Other props • Rev
- 24. Final Deliverables Standard Profiling Attributes • Audience
- 25. Final Deliverables Standard Profiling Attributes • Platform
- 26. Final Deliverables Standard Profiling Attributes • Prop
- 29. JANA KNOWS DATA. Joe Storbeck (210) 616-0083 x215 jstorbeck@janacorp.com JANA Main (210) 616-0083 solutions@janacorp.com We thank you for participating! Matthew Cassi (210) 309-5944 mcassi@janacorp.com www.janacorp.com
Hinweis der Redaktion
- Hello and welcome to the JANA Inc. “DITA Workflow 101” webinar, we thank you for your interest and attendance today. We know you’re all very busy people, so making the time to attend today’s webinar is much appreciated. My name is Matthew Cassi and I’m joined today by one of JANA’s DITA experts Joe Storbeck. Before we go into Joe’s background, let us first give you some JANA history. (click)
- For those of you who might not be familiar with JANA, we are a technical documentation services company established in San Antonio, Texas, in 1973. For 43 years, our core business has been the development, management and delivery of quality technical documentation. We have the expertise and the resources necessary to support a project of any size in the authoring, conversion, management, and publishing of quality content, with over 10 years of experience implementing the DITA standard. But first, you might just be wondering who your presenters are – (click)
- As I stated earlier my name is Matthew Cassi and I’ll be your presenter today. As an account executive for JANA, I represent a point of contact for our clients, but I’m sure you’d rather hear about JANA’s DITA consultation and development leader – Mr. Joe Storbeck. Welcome, Joe. (Thanks, Matt.) Joe has been a technical communication professional for over 30 years with an extensive background in the development of structured data and data application methodologies, leading technical documentation teams for some of the worlds largest and most successful companies, including IBM, Citibank and AIG. He is also recognized as an expert in the development and application of the DITA standard. (click)
- Joe’s Dialogue - Thank you, I’m excited to be here today! Coupled with being a consultant for JANA, I regularly teach classes on topic-based authoring and I publish a DITA related blog called – THE DITA SOURCE – which you can view at the JANA website. To give you a little more background, during my time at IBM, I worked directly with the team responsible for developing the DITA architecture. MATT - Thanks Joe. (CLICK) So you can check out Joe’s DITA Source blog at janacorp.com/blog. Don’t worry, if you missed it, we’ll provide a link to Joe’s blog in our Webinar follow up email. So, now that we’ve got that out of the way, let’s walk through today’s agenda. (click)
- Here’s a quick overview of today’s webinar agenda. While we expect this webinar to last around 30 minutes, we will try to keep the last 5 minutes or so free for answering any questions that you might have. You will notice that there is a box in the attendee panel that you can use anytime to submit a question. Our production team here will collect the questions as we go, and Joe and I will try to answer as many of those as we can before we close. You can see from the agenda that we’re really going to be focused on the discussion of the overall workflow, but we want to make sure that we start out the discussion with an overview of the types of people who will be involved, so lets take a quick look at some of the different roles that are important to the process, and some of the responsibilities that each member has to ensure a successful DITA project.
- As an organization investigates moving to a DITA writing environment, new roles, responsibilities, and skills must be identified as many individuals must work together to develop tools, procedures, and processes for the new environment. We have identified four basic roles that are necessary for a successful DITA implementation, although the number and different types of roles might change based on the complexity of your conversion needs. The roles can also vary significantly when moving past the conversion phase and into the authoring phase. In any case, the best DITA adoption results occur when key roles collaborate closely together.
- Matt - Let’s take a closer look at each of the four roles that we have identified, and note that we’re talking about these roles as an individual but there may be a number of people within your organization that perform each role. Joe why don’t you first tell us about what functions the Information Architect would perform as part of the DITA team. Joe - OK. The Information Architect is very familiar with the organization’s content and understands it’s life cycle. These individuals often act as the key DITA Evangelists within your organization – explaining what to expect in terms of changes to procedures and processes, and getting your IT team on board. They would also Manage the conversion process & defines milestones, and evaluate when and how documents will be converted or authored. The IA also designs the overall navigation, tracks progress and reports status. The Information architect determines where and how topics should be presented. Also note that there may multiple people in this and any other role. Matt – Okay, and how about the Author? (click) Joe - Authors are the individuals who, upon completion of training, begin writing content in DITA, often times learning the tools & processes as they go. They also can create pre-conversion and new topic outlines, and track ID’s and Filenames (for fixing broken links later). They are usually also responsible for authoring new material, running the conversion scripts, and performing the post-migration file clean-up. Matt – Next we have the role of Editor (CLICK) Joe can you elaborate on their responsibilities? Joe – Sure, this individual ensures that all authors are using the DITA elements and attribute values consistently, making sure that language and structure meet requirements for usability and clarity, and that all possible reuse is being employed. Additionally, they review document outlines and provide guidance to writers during the conversion and authoring process. Matt – and lastly we have the role of the person that we’re going to refer to as the Tech Tools Guru - (click) Joe – Yes, the Tech Tools Guru is important because you will need someone on your team who really understands your new toolset and the vendors you will be working with – someone who will understand your customizations and how everything works together. They will also help writers with tagging issues, debugging build and stylesheet problems and they can also create a conversion script. Matt – Thanks Joe, please also remember that these are just a few examples of some of the key roles you need to identify for a successful DITA conversion. Your specific needs might dictate that additional roles may or may not be needed, like a DITA sponsor or a Translation manager. Up next is a depiction of the sample Implementation Roadmap we’ll be using throughout this presentation. (click)
- Matt - On your screen now is a typical DITA implementation roadmap: From Data Analysis all the way through the publishing of the Final Deliverables. The roadmap before you breaks down the steps by phase: Data Analysis, Architecture Strategy Development, Technology Evaluation & Selection, Training, Conversion & Authoring Effort, Style Sheet Development and Final Deliverables. This scenario takes for granted that you will be converting (or at least, considering converting) portions of your existing product library. If you’re developing content from scratch some of these steps may not be applicable to you. Also these steps do not have to be in this particular order; keep in mind that DATA Analysis should always be your first step, but the specific order of the 5 intermediate steps can be interchangeable to follow your specific data conversion needs. But first, as a quick and dirty attempt to collect some information that will guide us through the rest of the webinar, we’d like to know which of these steps our attendees are having the most trouble with. You’ll see a survey pop up on your screen, so please take a few seconds to answer this question for us. (launch poll) We will use the data to customize some of the more topic-flexible portions of this presentation, and to give us an idea of what topics we might want to cover in upcoming webinars. (show poll results) Joe - OK. It looks like the majority of you are having trouble with (largest poll results). We will make sure that we cover it in more detail when we get to that portion of the webinar. (hide results) (click next screen)
- Matt - Now let’s start by taking a look at the Data Analysis phase. In the decade-plus that we’ve been performing services in the DITA world, we’ve talked to company after company who did not take the time to evaluate their data prior to performing the other steps. Analyzing your data first will allow you to make an informed decision when performing each of the later steps, especially architecture strategy development and technology selection. If you have legacy data that you need to convert, it is especially important to take the time to review your existing content. There are a number of critical questions that have to be asked and answered prior to starting a DITA conversion and authoring effort, and you have to get to know your data before any of these questions can be answered. (click)
- Matt – Questions like those shown here will help to identify the variables and define the information you will need later on, especially in the Conversion and Authoring and Technology Evaluation stages. Additionally, questions such as: Will you be able to create scripts to do the conversion? or Will you need to select tools that will help automate portions of the conversion? The entire scope of your project can change depending on the answer to a single question, and the answer may not be applicable to the entire data set. For instance, if your existing library is in a structured environment, your project will look very different from one which is converting data written using a desktop publishing package. The steps that you need to take will be determined by the structure of your existing data. You may find that a customized set of conversion scripts is the best method to convert your data, or you may be able to get away with a simple cut and paste using a piece of DITA-smart authoring software. Data analysis is also where you can determine what portions of your documents and library can be marked for reuse. This stage is where you will inform how much rewriting you will need to do when moving your documentation into DITA topic types. Joe – BTW, keep in mind that a typical roadmap for a dita conversion would progress from data analysis to architecture strategy development, which is how we’re going to progress in this presentation but there may be characteristics of your data that necessitate performance of steps in another order. Trust your data to show you the way. CLICK
- Matt - Architecture Strategy Development: After thoroughly analyzing your legacy data, but before converting data or authoring any new content, you should begin planning the strategies that you are going to employ when you begin to build-out your DITA project. Take the time to develop intelligent strategies - strategies that involve moving existing data into the various elements, or maybe repurposing existing DITA elements to fit your needs - while always trying to stay within the framework of the DITA standard.
- JOE - Your information architect should be the final arbiter for the structure of your document. (The IA should work closely with writers to create pre-conversion outlines and new topic outlines. The IA should also design the overall navigation and determine where and how topics will be presented. Writers should keep track of filenames as well as topic and element IDs that will be used later for fixing broken links. By organizing content into small chunks, it is much easier to re-use content for multiple outputs. When content is structured this way, it becomes possible to freely mix-and-match the content so that it can suit the needs of different users. DITA also allows the writer to set conditions for the audience, products, version, and platforms. The writer can then use these conditions to produce different outputs for different types of users. For example, you may need to write a help system for a software application that is available in both Windows and UNIX versions. The functionality of the application is similar in both operating systems, but there are a few differences between the Windows and Unix versions. By using the platform attribute, you can indicate which operating system the topic covers. When you publish your files, you can use the platform attribute to produce documentation for both operating systems. We’ll focus on these attributes later when we discuss the final deliverables phase. (CLICK)
- Matt – Technology Evaluation Selection: So once you have taken the time to understand your data and how it fits into your overall architecture strategies, you can begin the search for the software that best fits your company’s requirements. Choosing the right authoring software and CMS for your organization is a critical step in ensuring the success of the overall project. (CLICK)
- Matt - Take your time with this step. This is one of the biggest potential stumbling blocks in a successful and efficient DITA implementation. We have talked to many companies that, once they got approval and the money for a DITA implementation, immediately invested a good portion of their budget in technology that didn’t fit their needs. The folks doing the buying either didn’t talk to the folks that analyzed the data, or the Information Architects weren’t consulted regarding the library structure and output, or they skipped the data analysis altogether. One company bought technology they didn’t fully understand and after a full year of dedicated conversion effort they had converted only one manual to DITA - a small fraction of the several hundred titles within their library of legacy data. JOE - A few quick tips to make sure that you don’t fall prey to the potential pitfalls in this step: Do your homework in the two previous steps. Once you understand your data and how it fits into your overall architecture strategies, you can begin the search for the software that best fits your company’s requirements. Choosing the right authoring software and/or Content Management System for your organization is perhaps the most important step in ensuring the success of the overall project. Make sure that you leverage the information that you have gathered to make an informed decision for both. Don’t be afraid to move on to the another step before making a final decision on what CMS to use. The CMS can be the most critical decision you make. Don’t rush it!! Also, I think that it’s important to note here that DITA does not necessarily require the use of a CMS. After looking at all of the options and project variables you may decide that it’s best for your organization to move forward without a CMS. This is a perfectly legitimate alternative, although what you’ll typically find is that the larger the scale of your DITA project, the more benefits you will get from using a CMS to manage the use and storage of your DITA topic files. (CLICK)
- Matt - Training: Authoring and converting DITA topics is about more than just knowing what information goes where. It requires an understanding of the benefits of using the DITA standard, as well as the benefits of topic-based authoring. Writers who understand both are going to be a major asset to the authoring and conversion team. JOE – Keep in mind that training can happen at any time prior to authoring and conversion, but the training should happen as close to the start of the authoring and conversion effort as possible. CLICK
- Matt - Also, you might want to give your editor or tech tools guru the training task. That person can act as a counselor for writers as they move through the DITA implementation. Writers are always tempted to find short cuts. They are creative! And they will find ways to achieve goals that are outside of the DITA standard. The training person should review DITA tags to ensure they are used in the correct fashion. We also want to point out that writers need training to avoid the many pitfalls that are possible. DITA introduces changes that will affect writers and developers differently. Plan for the change and allow time for real learning. Don’t just throw DITA at your staff and hope for the best. Joe –DITA can seem intimidating to writers at first. As mentioned in one of our previous webinars, when I was teaching DITA to writers at IBM one woman told me that she wasn’t going to learn DITA, she told me should would rather retire than go through that. And……she did! That’s when we realized that in addition to educating our writers on how to use DITA we had to also educate them on WHY we we’re using DITA. CLICK
- You may need to convince writers that topic-based writing works. Here’s how you can show them the differences: JOE – if you look at this chart, it shows the major differences between Book and Topic-based Structure. In it’s most basic form topic-based documentation provides the individual building blocks for quality documentation. Topic-based documentation gets to the point. Each topic answers one questions – How Do I….? – What is….? – What went wrong….? – Topics should only be a few paragraphs long, stick to one subject and they should be able to stand on their own. CLICK
- Next we have the Conversion & Authoring Efforts: This is the step where all of the work that you have done in each of the preceding steps pays off for you, in the form of efficient automated conversions and intelligent topic-based authoring.
- Everyone should be involved in this effort. And it is important to remember that you might need to---no---you WILL need to do rework. Automated conversion tools can’t and won’t achieve a conversion. You are always going to have to do rework and cleanup. Before you start your conversion: Clean up tags Create a topic-based outline Look for duplicate information If your writing staff is large, you might want to create a regularly scheduled meeting in which the staff can discuss problems or questions they are having with DITA tagging and formatting. You could use these sessions to create a Best Practices document for future projects and staff members. When your writers realize that EVERYONE is learning, the transition to topic-based authoring is easier. After your conversion: Fix any formatting problems Fix broken links Verify that topics have been typed correctly CLICK
- And now we move to the development of Stylesheets: While Stylesheets are needed to transform XML source into output, most DITA-smart software titles will come with a series of out of the box Stylesheets you can use if you want to publish your data with no bells or whistles. But if you want to customize the output, such as maybe highlighting elements, you can customize the existing stylesheet in order to do so. If you want a new specialization, you’ll need to create a new stylesheet. However, we strongly suggest you not create new specializations unless you’re well versed in the different customization features. Because each rendering application is different, each distinct output type requires a different transform and a different formatting stylesheet. CLICK
- Output options include, but not limited to, PDF, WebHelp, CHUM, EPUB, JavaHelp, Eclipse Help, XHTML and other structured models. - each requiring its own stylesheet(s). Stylesheets may be written in a variety of languages. For example, XSL, CSS, CSS3, DSSSL, and FOSI. Additionally, there are many tools that can process your stylesheets. Please note that not every processing tool renders identically. Be sure to choose a language and tool set that suits your needs and is sustainable. CLICK
- Final Deliverables: Once your data has been properly converted and authored and your style sheets have been developed, outputting and publishing your data should be as easy as pushing a button - that’s the true beauty of DITA. CLICK
- Your final delivery may be a PDF and an online document. You only need one dataset with DITA! JOE - One of the most useful features in DITA is Conditional Processing (or Profiling), which allows you to use the same set of source files to create different versions of your documentation. Content is marked in a way that you can filter out entire topics, paragraphs, sentences, and even words. DITA offers a set of standard self-explanatory profiling attributes that are applicable to most elements – For example the Audience element (CLICK)
- Suppose you are writing a topic for an audience that includes both advanced and novice users. A novice will need more explanation than an advance user, so if you notice in the outlined paragraphs, the paragraph tags have the audience attribute listed as novice. An advanced user would know what this information means without having to read it. So when you produce the documentation for the novice user, your ditaval file would read “Include Audience = Novice”. And all of those paragraphs would show up in your final documentation. If you’re producing documentation for an advanced user, in the ditaval file you would indicate “Exclude Audience = Novice”. The resulting transform would exclude that paragraphs intended for the novice audience.
- In this next example we have commands listed in both Unix and Windows styles. In the outlined tag you’ll see there is a platform attribute that says either windows or unix. To produce documentation for the windows format your DITAVAL file would indicate “Include platform=windows Exclude platform=Unix” To create the unix only documentation your DITAVAL file would indicate “Exclude platform=windows Include platform=Unix”
- Our last attribute is “PROPS”. In the example you’ll see it indicates that the database can be installed on a desktop or laptop device, suppose you have a customer that thinks desktops are history and only want references to the laptop, the offending word is in your short description, do you want to create two short descriptions and label them with the appropriate attributes? You could attack the offending words directly using the PH tag and the PROPS attribute as seen in the example. Note that the word “OR” is also tagged, if it isn’t excluded the sentence will not make sense. To exclude the desktop reference your DITAVAL file will indicate “exclude Props = Desktop”. These three attribute are just an example of the attirbutes available within DITA.
- We have now laid out for you a basic roadmap to a successful DITA implementation, but we want to restate that the path that we have laid out is simply a depiction of a typical path from start to finish. The specific steps and the order of the steps will change for every company. If you are unsure of the order that makes sense for your company, or if your DITA project is stuck in one of these steps, give us a call. This is what we do. JANA has helped many companies in their efforts to build a DITA library by providing the expertise and the manpower required to see a project through to completion. As a respected provider of technical documentation services for over 40 years, JANA has extensive resources that it can bring to bear on your project – no matter the size. If you have questions for the panel, get them ready now because we are about to move on to the Q & A session, but before we do, we also want to mention the importance of conducting a DITA pilot project. A small-scale DITA pilot project will provide course direction and help you decide how to focus your implementation plan. It will also help you determine where your strengths and weaknesses lie, and will increase your odds of a successful large-scale DITA implementation. CLICK
- At this time we’ll answer the questions submitted during today’s webinar and if we have time remaining we’ll answer any additional questions as well. (CLICK when q/a is over)
- Great, thanks Joe. So, that concludes our webinar today, we thank you for your questions and participation. If you would like to speak to us in more detail or know more about JANA’s DITA consulting solutions please don’t hesitate to reach out to us. Remember, JANA has the expertise and the resources necessary to support a project of any size in the authoring, conversion, management, and publishing of quality content, with over 10 years of experience implementing the DITA standard. We hope that each of you have a great remainder of the day and thank you again for attending this Webinar. Look for a follow-up email later today.