DITA - AN OVERVIEW My Example of Using Video in DITA DITA - An Overview Thoughts about technical writing and my role in it. And no, I won't give up on what I did fifteen years ago. It is the foundation under what I am today. So my resume is seven pages long. My career is longer than that. Technical documentation refers to all of the information about how to select, prepare for, receive, unpack, implement and optimally use and maintain a product. A single company may sell only one product, or a dozen, or more. And every product, every variant of it, every SKU, must be accompanied with excellent documentation. Translating user guides, implementation guides, administration guides, quick setup guides, unpacking instructions, modular hot swap procedures, and all of the other information is an expensive proposition. In these United States, we begin with an English original version, which is translated into FIGS: French, Italian, German and Spanish. That covers North America and much of Western Europe. If the product is marketed globally, the price is substantial. Some Asian languages can be as costly as $.50 per word. (Reportedly even higher in some situations.) Corporations have a tremendous amount of product documentation to keep in order. Billions of words. Published in thousands of documents. And the same text can often apply to video scripts and marketing spec sheets and web content. In the midst of all this hullabaloo is the reader. Sitting in a chair near a window in the library. With paper and reflected light and birds singing. The reader has not changed. Not since she first stood with her head craned back to study the pictures in Lascaux. The learner has not changed. The message has not changed. Information still must be organized and delivered properly and with respect for the process of learning. It does not matter to the reader that the system the corporation uses to maintain, manage, and deliver content has changed. The user still has to put together an Ikea shelf, or an HP printer, or anything that can be produced. They must use the software. They must rebuild the transmission. Then, now, and forever, a book is a valuable thing. It is and always has been as 1 DITA - AN OVERVIEW HOW TO PROPERLY INTEGRATE DITA sacrosanct as a Super Bowl football. People learn by reading books. Studying images. Reading captions. Following methodical instruction, while also learning context. Jumping ahead to the other chapters. Peeking in the glossary. Studying the table of contents. Writing in the margins. Occasionally, (according to Mortimer J. Adler), if the content is entirely engaging, dog earing the pages, and even throwing the book against the wall in exasperation and leaving it for awhile, before coming back ready to try again. It is all part of being an engaged reader, active in the active process of reading. It is formidably frightening the number of professional college professors who somehow believe showing a mechanic the 47 steps for tearing down a transmission qualifies them to put it back together again. A book has chronology. Context. When you write a book, you write the story of the thing. You explain how it is done. You cover all the bases. Then, after the book is finished, and the reader is served, if you absolutely MUST break it into a dictionary of topics, have at it. But don’t neglect to write the book first. How to Properly Integrate DITA • Talk to subject matter experts. • Wheel the prototype into your workspace and study it. • Find out if the blades will cut off your fingers if you pull out the drawer with the fans still spinning. Make a stink about it. The smart managers will notice and prize your willingness to risk getting fired to keep them out of the losing end of a lawsuit. • Outline the finest book you can imagine. • Write and illustrate the book. • Discuss it with product managers and quality assurance pros. Put it in front of a competent learner/user and watch what they do with it. • Get feedback and ultimately earn sign off from engineering and legal. • NOW, break the book down into topics. • Translate it. • Hire some competent technician to reconstruct the book using Oxygen or some other XML interface. • Distribute the book with some pride. It is a book, not a dictionary. An ode to a worthy reader. Look at this video. 2 DITA - AN OVERVIEW TOGGLE TO THE STRUCTURED VERSION OF FRAMEMAKER Toggle to the Structured Version of FrameMaker It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Turn on FrameMaker. 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RESULT: Here is the result! RELATED LINKS: To create a map It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Watch this video. (http://davelance.com/dita_files_david_lance/video/v_create_a_map.mp4) 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 3 DITA - AN OVERVIEW CREATE TOPICS IN A MAP 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RESULT: Here is the result! RELATED LINKS: Create topics in a map It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Watch this video. (http://davelance.com/dita_files_david_lance/video/v_create_topics_in_a_map.mp4) 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RESULT: Here is the result! RELATED LINKS: Set up the structure of DITA It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is 4 ENTER CONTENT IN A REFERENCE TOPIC SET UP THE STRUCTURE OF DITA provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Turn on FrameMaker. 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RELATED LINKS: Enter Content in a Reference Topic Thoughts about technical writing and my role in it. And no, I won't give up on what I did fifteen years ago. It is the foundation under what I am today. So my resume is seven pages long. If you don't like it, continue to not hire me. Technical documentation refers to all of the information about how to select, prepare for, receive, unpack, implement and optimally use and maintain a product. One company may have one product, or a dozen, or more. And every product, every variant of it, every SKU must be accompanied with excellent documentation. Translating user guides, implementation guides, administration guides, quick setup guides, unpacking instructions, modular hot swap procedures, and all of the other information is an expensive proposition. In these United States, we begin with an English original version, which is translated into FIGS: French, Italian, German and Spanish. That covers North America and much of Western Europe. If the product is marketed globally, the price is substantial. Some Asian languages can be as costly as $.50 per word. (Reportedly even higher in some situations.) Corporations have a tremendous amount of product documentation to keep in order. Billions of words. Published in thousands of documents. And the same text can often apply to video scripts and marketing spec sheets and web content. 5 ENTER CONTENT IN A REFERENCE TOPIC HOW TO PROPERLY INTEGRATE DITA In the midst of all this hullabaloo is the reader. Sitting in a chair near a window in the Arboretum. With paper and reflected light and birds singing. The reader has not changed. Not since she first stood with her head craned back to study the pictures in Lascaux. The learner has not changed. The message has not changed. Information still must be organized and delivered properly and with respect for the process of learning. It does not matter to the reader that the system the corporation uses to maintain, manage, and deliver content has changed. The user still has to put together an Ikea shelf, or an HP printer, or anything that can be produced. They must use the software. They must rebuild the transmission. Then, now, and forever, a book is a valuable thing. It is and always has been as sacrosanct as a Super Bowl football. People learn by reading books. Studying images. Reading captions. Following methodical instruction, while also learning context. Jumping ahead to the other chapters. Peeking in the glossary. Studying the table of contents. Writing in the margins. Occasionally, (according to Mortimer J. Adler), if the content is entirely engaging, dog earing the pages, and even throwing the book against the wall in exasperation and leaving it for awhile, before coming back ready to try again. It is all part of being an engaged reader, active in the active process of reading. It is formidably frightening the number of professional college professors who somehow believe showing a mechanic the 47 steps for tearing down a transmission qualifies them to put it back together again. A book has chronology. Context. When you write a book, you write the story of the thing. You explain how it is done. You cover all the bases. Then, after the book is finished, and the reader is served, if you absolutely MUST break it into a dictionary of topics, have at it. But don’t neglect to write the book first. How to Properly Integrate DITA 6 • Talk to subject matter experts. • Wheel the prototype into your workspace and study it. • Find out if the blades will cut off your fingers if you pull out the drawer with the fans still spinning. Make a stink about it. The smart managers will notice and prize your willingness to risk getting fired, and even dispossesed to keep them out of the losing end of a lawsuit! • Outline the finest book you can imagine. • Write and illustrate the book. • Discuss it with product managers and quality assurance pros. Put it in front of a competent learner/user and watch what they do with it. • Get feedback and ultimately earn sign off from engineering and legal. ENTER CONTENT IN A REFERENCE TOPIC CONFIRM YOU ARE IN AUTHORING VIEW • NOW, break the book down into topics. • Translate it. • Hire some competent technician to reconstruct the book using Oxygen or some other XML interface. • Distribute the book with some pride. It is a book, not a dictionary. An ode to a worthy reader. Look at this video. Confirm you are in authoring view It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Turn on FrameMaker. 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RELATED LINKS: Turn on Element boundries It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. 7 ENTER CONTENT IN A REFERENCE TOPIC TOGGLE TO THE XML CODE VIEW Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Turn on FrameMaker. 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RELATED LINKS: Toggle to the XML code view It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Turn on FrameMaker. 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RELATED LINKS: 8 ENTER CONTENT IN A CONCEPT TOPIC TOGGLE TO THE XML CODE VIEW Enter Content in a Concept Topic Thoughts about technical writing and my role in it. And no, I won't give up on what I did fifteen years ago. It is the foundation under what I am today. So my resume is seven pages long. If you don't like it, continue to not hire me. Technical documentation refers to all of the information about how to select, prepare for, receive, unpack, implement and optimally use and maintain a product. One company may have one product, or a dozen, or more. And every product, every variant of it, every SKU must be accompanied with excellent documentation. Translating user guides, implementation guides, administration guides, quick setup guides, unpacking instructions, modular hot swap procedures, and all of the other information is an expensive proposition. In these United States, we begin with an English original version, which is translated into FIGS: French, Italian, German and Spanish. That covers North America and much of Western Europe. If the product is marketed globally, the price is substantial. Some Asian languages can be as costly as $.50 per word. (Reportedly even higher in some situations.) Corporations have a tremendous amount of product documentation to keep in order. Billions of words. Published in thousands of documents. And the same text can often apply to video scripts and marketing spec sheets and web content. In the midst of all this hullabaloo is the reader. Sitting in a chair near a window in the Arboretum. With paper and reflected light and birds singing. The reader has not changed. Not since she first stood with her head craned back to study the pictures in Lascaux. The learner has not changed. The message has not changed. Information still must be organized and delivered properly and with respect for the process of learning. It does not matter to the reader that the system the corporation uses to maintain, manage, and deliver content has changed. The user still has to put together an Ikea shelf, or an HP printer, or anything that can be produced. They must use the software. They must rebuild the transmission. Then, now, and forever, a book is a valuable thing. It is and always has been as sacrosanct as a Super Bowl football. People learn by reading books. Studying images. Reading captions. Following methodical instruction, while also learning context. Jumping ahead to the other chapters. Peeking in the glossary. Studying the table of contents. Writing in the margins. Occasionally, (according to Mortimer J. Adler), if the content is entirely engaging, dog earing the pages, and even throwing the book against the wall in exasperation and leaving it for awhile, before coming back ready to try again. It is all part of being an engaged reader, active in the active process of reading. It is formidably frightening the number of professional college professors who somehow believe showing a mechanic the 47 steps for tearing down a transmission qualifies them to put it back together again. A book has chronology. Context. When you write a book, you write the story of the thing. You explain how it is done. You cover all the bases. Then, after the book is finished, and the reader is served, if you 9 ENTER CONTENT IN A CONCEPT TOPIC HOW TO PROPERLY INTEGRATE DITA absolutely MUST break it into a dictionary of topics, have at it. But don’t neglect to write the book first. How to Properly Integrate DITA • Talk to subject matter experts. • Wheel the prototype into your workspace and study it. • Find out if the blades will cut off your fingers if you pull out the drawer with the fans still spinning. Make a stink about it. The smart managers will notice and prize your willingness to risk getting fired to keep them out of the losing end of a lawsuit. • Outline the finest book you can imagine. • Write and illustrate the book. • Discuss it with product managers and quality assurance pros. Put it in front of a competent learner/user and watch what they do with it. • Get feedback and ultimately earn sign off from engineering and legal. • NOW, break the book down into topics. • Translate it. • Hire some competent technician to reconstruct the book using Oxygen or some other XML interface. • Distribute the book with some pride. It is a book, not a dictionary. An ode to a worthy reader. Look at this video. How to insert images It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. 10 ENTER CONTENT IN A CONCEPT TOPIC INSERT CROSS REFERENCES TASK 1. Turn on FrameMaker. 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RELATED LINKS: Insert cross references It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Turn on FrameMaker. 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RELATED LINKS: 11 ENTER CONTENT IN A TASK TOPIC INSERT CROSS REFERENCES Enter Content in a Task Topic Thoughts about technical writing and my role in it. And no, I won't give up on what I did fifteen years ago. It is the foundation under what I am today. So my resume is seven pages long. If you don't like it, continue to not hire me. Technical documentation refers to all of the information about how to select, prepare for, receive, unpack, implement and optimally use and maintain a product. One company may have one product, or a dozen, or more. And every product, every variant of it, every SKU must be accompanied with excellent documentation. Translating user guides, implementation guides, administration guides, quick setup guides, unpacking instructions, modular hot swap procedures, and all of the other information is an expensive proposition. In these United States, we begin with an English original version, which is translated into FIGS: French, Italian, German and Spanish. That covers North America and much of Western Europe. If the product is marketed globally, the price is substantial. Some Asian languages can be as costly as $.50 per word. (Reportedly even higher in some situations.) Corporations have a tremendous amount of product documentation to keep in order. Billions of words. Published in thousands of documents. And the same text can often apply to video scripts and marketing spec sheets and web content. In the midst of all this hullabaloo is the reader. Sitting in a chair near a window in the Arboretum. With paper and reflected light and birds singing. The reader has not changed. Not since she first stood with her head craned back to study the pictures in Lascaux. The learner has not changed. The message has not changed. Information still must be organized and delivered properly and with respect for the process of learning. It does not matter to the reader that the system the corporation uses to maintain, manage, and deliver content has changed. The user still has to put together an Ikea shelf, or an HP printer, or anything that can be produced. They must use the software. They must rebuild the transmission. Then, now, and forever, a book is a valuable thing. It is and always has been as sacrosanct as a Super Bowl football. People learn by reading books. Studying images. Reading captions. Following methodical instruction, while also learning context. Jumping ahead to the other chapters. Peeking in the glossary. Studying the table of contents. Writing in the margins. Occasionally, (according to Mortimer J. Adler), if the content is entirely engaging, dog earing the pages, and even throwing the book against the wall in exasperation and leaving it for awhile, before coming back ready to try again. It is all part of being an engaged reader, active in the active process of reading. It is formidably frightening the number of professional college professors who somehow believe showing a mechanic the 47 steps for tearing down a transmission qualifies them to put it back together again. A book has chronology. Context. When you write a book, you write the story of the thing. You explain how it is done. You cover all the bases. Then, after the book is finished, and the reader is served, if you 12 PUBLISH AS A PDF DOCUMENT HOW TO PROPERLY INTEGRATE DITA absolutely MUST break it into a dictionary of topics, have at it. But don’t neglect to write the book first. How to Properly Integrate DITA • Talk to subject matter experts. • Wheel the prototype into your workspace and study it. • Find out if the blades will cut off your fingers if you pull out the drawer with the fans still spinning. Make a stink about it. The smart managers will notice and prize your willingness to risk getting fired to keep them out of the losing end of a lawsuit. • Outline the finest book you can imagine. • Write and illustrate the book. • Discuss it with product managers and quality assurance pros. Put it in front of a competent learner/user and watch what they do with it. • Get feedback and ultimately earn sign off from engineering and legal. • NOW, break the book down into topics. • Translate it. • Hire some competent technician to reconstruct the book using Oxygen or some other XML interface. • Distribute the book with some pride. It is a book, not a dictionary. An ode to a worthy reader. Look at this video. Publish as a PDF document Thoughts about technical writing and my role in it. And no, I won't give up on what I did fifteen years ago. It is the foundation under what I am today. So my resume is seven pages long. If you don't like it, continue to not hire me. Technical documentation refers to all of the information about how to select, prepare for, receive, unpack, implement and optimally use and maintain a product. One company may have one product, or a dozen, or more. And every 13 PUBLISH AS A PDF DOCUMENT HOW TO PROPERLY INTEGRATE DITA product, every variant of it, every SKU must be accompanied with excellent documentation. Translating user guides, implementation guides, administration guides, quick setup guides, unpacking instructions, modular hot swap procedures, and all of the other information is an expensive proposition. In these United States, we begin with an English original version, which is translated into FIGS: French, Italian, German and Spanish. That covers North America and much of Western Europe. If the product is marketed globally, the price is substantial. Some Asian languages can be as costly as $.50 per word. (Reportedly even higher in some situations.) Corporations have a tremendous amount of product documentation to keep in order. Billions of words. Published in thousands of documents. And the same text can often apply to video scripts and marketing spec sheets and web content. In the midst of all this hullabaloo is the reader. Sitting in a chair near a window in the Arboretum. With paper and reflected light and birds singing. The reader has not changed. Not since she first stood with her head craned back to study the pictures in Lascaux. The learner has not changed. The message has not changed. Information still must be organized and delivered properly and with respect for the process of learning. It does not matter to the reader that the system the corporation uses to maintain, manage, and deliver content has changed. The user still has to put together an Ikea shelf, or an HP printer, or anything that can be produced. They must use the software. They must rebuild the transmission. Then, now, and forever, a book is a valuable thing. It is and always has been as sacrosanct as a Super Bowl football. People learn by reading books. Studying images. Reading captions. Following methodical instruction, while also learning context. Jumping ahead to the other chapters. Peeking in the glossary. Studying the table of contents. Writing in the margins. Occasionally, (according to Mortimer J. Adler), if the content is entirely engaging, dog earing the pages, and even throwing the book against the wall in exasperation and leaving it for awhile, before coming back ready to try again. It is all part of being an engaged reader, active in the active process of reading. It is formidably frightening the number of professional college professors who somehow believe showing a mechanic the 47 steps for tearing down a transmission qualifies them to put it back together again. A book has chronology. Context. When you write a book, you write the story of the thing. You explain how it is done. You cover all the bases. Then, after the book is finished, and the reader is served, if you absolutely MUST break it into a dictionary of topics, have at it. But don’t neglect to write the book first. How to Properly Integrate DITA 14 • Talk to subject matter experts. • Wheel the prototype into your workspace and study it. PUBLISH AS A PDF DOCUMENT SAVE A .PDF DOCUMENT OF THE MAP • Find out if the blades will cut off your fingers if you pull out the drawer with the fans still spinning. Make a stink about it. The smart managers will notice and prize your willingness to risk getting fired to keep them out of the losing end of a lawsuit. • Outline the finest book you can imagine. • Write and illustrate the book. • Discuss it with product managers and quality assurance pros. Put it in front of a competent learner/user and watch what they do with it. • Get feedback and ultimately earn sign off from engineering and legal. • NOW, break the book down into topics. • Translate it. • Hire some competent technician to reconstruct the book using Oxygen or some other XML interface. • Distribute the book with some pride. It is a book, not a dictionary. An ode to a worthy reader. Look at this video. Save a .PDF document of the map It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Turn on FrameMaker. 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. 15 THE IS A REFERENCE TOPIC WITH A TABLE VIEW A .PDF DOCUMENT IN ADOBE ACROBAT RELATED LINKS: View a .PDF document in Adobe Acrobat It is not intuitive, how to toggle between the structured and unstructured versions of FrameMaker. It is hidden in the preferences menu. The procedure is provided below, if you must. Else, just open Edit > Preferences, and make your selection from the first droplist box. Reboot the application. Follow this procedure to toggle between unstructured and structured FrameMaker. TASK 1. Turn on FrameMaker. 2. Open >Edit > Preferences. 3. Select the version of FrameMaker you want to use from the Product Interface droplist. 4. Click OK. 5. Turn off FrameMaker. 6. Turn on FrameMaker. RELATED LINKS: The is a reference topic with a table Some introduction to some reference material will follow. This is a table with some referenceinformation in it. Here is an option for your reference.This option fits entirely in your frame of understanding the material at hand. It does not float off here in space as a disjointed entity. It is an organic part of your reading experience, else it insults your ability to learn from this material. Here is an option for your reference.This option fits entirely in your frame of understanding the material at hand. It does not float off here in space as a disjointed entity. It is an organic part of your reading experience, else it insults your intelligence. 16 THE IS A REFERENCE TOPIC WITH A TABLE VIEW A .PDF DOCUMENT IN ADOBE ACROBAT Here is an option for your reference.This option fits entirely in your frame of understanding the material at hand. It does not float off here in space as a disjointed entity. It is an organic part of your reading experience, else it is indifferent to where you are in the process. Here is an option for your reference.This option fits entirely in your frame of understanding the material at hand. It does not float off here in space as a disjointed entity. It is an organic part of your reading experience, else it insults you as a human being. 17
© Copyright 2024