[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Thoughts On Sections
One of the goals of instituting a new way of authoring and often a new content management system is to begin with sound content. It would be a better decision to leave legacy content out of the new system. You can refer to it, include it in maps, but otherwise acknowledge that it does not meet the new standards. If you spend much time and energy simply converting legacy content that does not comply with a topic-based model, what have you accomplished? For years, we saw organizations convert legacy content into XML DTDs that emulated their existing information model perfectly. Aside from possible cost savings in decreased production time, they didn't appear to have gained much except to create an environment that made it more cumbersome to author and review content. We need to have a discussion at some point about the process of migrating to DITA. My advice to organizations is to transform the content rather than migrate. Unless the legacy content is reasonably well structured, you will end up with a repository or a collection of topics that is not essentially different from your starting point. I don't believe it's the small organizations that have a problem. With less legacy content and a solid analysis of what should be transformed and what should be left outside of DITA/XML, small organizations with continuously changing information should be able to transform their existing content quickly and move to authoring new content. It's the industries like telecommunications with enormous legacy content that have a problem that requires thorough analysis and tough decision-making. One of the primary advantages of the DITA model is to reduce the cost of change in the future. Migrating legacy content "as is" simply maintains the status quo. The content is still largely unworkable. Transforming content to meet the model means that you will have a database that is pliable. Given 20 years of desktop publishing, we have created a legacy of content that is incredibly expensive to change, as Rob and Paul have both noted in their examples. If you do nothing to reduce the cost of change, why bother to spend all this time, money, and energy moving to DITA/XML? We might want to consider the concept of "technical debt." We have gotten ourselves into a huge technical debt with the way we have produced technical content for 20 years. Now seems the time to reduce the debt. I think the difficulty of decreasing costs is one reason for the stampede to outsource technical documentation to low-cost work forces. As you can tell, I'm quite passionate about this issue. JoAnn JoAnn T. Hackos, PhD President Comtech Services, Inc. 710 Kipling Street, Suite 400 Denver, CO 80215 303-232-7586 joann.hackos@comtech-serv.com www.comtech-serv.com -----Original Message----- From: Rob Frankland [mailto:torobf@earthlink.net] Sent: Friday, October 28, 2005 10:31 AM To: JoAnn Hackos; 'Paul Prescod'; dita@lists.oasis-open.org Subject: RE: [dita] Thoughts On Sections This discussion really addresses a critical conundrum with DITA in general. The line of thinking that stresses writing reusable concise topics is admirable. For users just adopting DITA, one of their biggest concerns is how they migrate their existing content into DITA. If the integration of legacy content requires huge rework, only the largest, most well-financed groups will take that the plunge. I think this tips the argument in favor of the approach Paul has suggested. It accommodates both points of views. It enables new content to be created expeditiously for single-sourcing and allows legacy content to be imported with less effort. Rob Rob Frankland 12408 Kallgren RD NE Bainbridge Island, WA 98110-3328 Phone: 206-780-8850 Email: torobf@earthlink.net -----Original Message----- From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com] Sent: Friday, October 28, 2005 5:48 AM To: Paul Prescod; dita@lists.oasis-open.org Subject: RE: [dita] Thoughts On Sections Would it not be preferable to advise users to consider developing these subconcept statements as individual topics that may then be more easily reused in other contexts? In most cases, the nesting into two or more levels of information is a formalism preferred by the writer rather than a useful construct for the reader. In most instances, when I review these structures, they are poorly structured. I know that we can't enforce good writing practices, but it's interesting to think we might try. If the authors were asked to write smaller conceptual topics, with better structuring of information to make the information more flat (and therefore perhaps more understandable), we could stay with the original design. If the nesting is really that important to understanding in the output context, the nesting could occur in the ditamap rather than in the topic itself. The smaller conceptual topics would also be more readily available for reuse in contexts where they should be standalone. Just some thoughts JoAnn JoAnn T. Hackos, PhD President Comtech Services, Inc. 710 Kipling Street, Suite 400 Denver CO 80215 303-232-7586 joann.hackos@comtech-serv.com -----Original Message----- From: Paul Prescod [mailto:paul.prescod@blastradius.com] Sent: Friday, October 28, 2005 6:41 AM To: dita@lists.oasis-open.org Subject: [dita] Thoughts On Sections On last week's call we discussed several different approaches to sections. My personal opinion on the current section element is that they are simultaneously too strict and too loose. We've discussed at length the sense in which they are too loose: they do not provide any guidance for authoring and overlap almost exactly with the content model of paragraph. On the other hand, sections are more strict than HTML "DIV" elements in a very important way: they cannot be nested. Some of our customers have a need for "grouper sections" that can wrap up other sections in their specializations. Basically their topics are not necessarily flat. For privacy reasons I'll make up an example structure: Part Description Subparts Subpart 1 description Subpart 2 description Subpart 3 description Use contexts Context 1 description Context 2 description Context 3 description The customer sees the "Part Description" as the topic level because the subparts are meaningless to the reader out of context of the parent. Therefore I feel that in the loose, designed-to-be-specialized base DITA topic type, sections should be nestable. Another key reason to allow sections to nest is to have a body-level container that can serve the "generic wrapper" role that phrases do at the inline level. Generic wrappers are useful as a basis for specialization, as a place to put filtering attributes and as a way to logically conref a set of content elements at once. I propose short-term and long-term directions for sections: DITA 1.1: they should be loosened to be generic wrappers that can nest. <!ENTITY % section.cnt "(#PCDATA | %basic.ph; | %basic.block; | %title; | %txt.incl; | section)*"> DITA 2.0: they should be tightened to be generic wrappers _of body elements_ with zero or one titles and no PCDATA. <!ELEMENT % section.cnt "(title? , %basic.block;)"> If we could agree on this direction then we wouldn't need a new structured-section element. But if it is important that section have basically the same content model as paragraph plus titles (I'm not sure why) then we probably do need structured-section. Paul Prescod
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]