OASIS Darwin Information Typing Architecture (DITA) TC

Regarding the challenge of helping people understand the distinction between "DITA" and "DITA OT", here are some thoughts stemming from training new (to structured authoring) authors, parts of which some people find a little alarming, but all of which I cling to nerdily and stubbornly nevertheless. It starts with separation of structure and formatting. I use this premise to motivate a pair of diagrams, simple enough that I think you can get them from these verbal descriptions:   1. For "traditional/DTP", there are two blobs in the diagram, one of which says "Authoring tool" and has an arrow pointing to the other, which says "Output".   2. For "structured authoring" the "Authoring tool" blob yields a "Structured document", which sits next to another (originless) blob called "Style sheets". Both of these blobs feed into another one called "Publishing system", which in turn points to the final blob "Output".   The mantra I use with these two diagrams is "With structured authoring you are not creating output; you are creating input." E.g., you are not saying "This stuff should have a box around it and be positioned over that-a-way"; you are only saying "This stuff is a sidebar". Then the publishing system says "Oh yeah, I know what to do with that."   From there it is an easy step to discussing the following very real process, strongly similar to the code-test-debug cycle in programming:   1. Write some code (XML/content). 2. Generate output. 3. Examine the output for correctness. 4. Fix errors and go to step 2.   I talk of the giddy anticipation when you're about to generate output again, the disappointment when it's still broken, and of course that eventual rush when you finally do get it right.   The "fix errors" part is a burden potentially shared by both authors and style sheet developers, which does complicate matters. As far as the analogy goes, this can be handwaved a bit by the fact that we are teaching authors about their particular perspective on this ecosystem. But this also gives an opportunity to discuss the negotiations/compromises that sometimes must be made between markup design, markup usage, and style sheet development effort. (Similar negotiations may occur between product management and development in a programming shop, btw.)   I think you could possibly push this analogy further with comparisons between DITA and programming languages, but I have not needed them, or thought them out enough to be sure how well it would work.   While I admit that this analogy may be a little scary to folks who think programming is intimidating, I also think that it helps strengthen the basic premise of separation of structure from formatting that really is fundamental to understanding why DITA <> DITA OT. The cyclical process with "write code" and "generate output" in different stages reinforces that they are different parts of the system.   mag  

During the discussion, I was thinking instead of an infographic explainer of The DITA Ecosystem showing graphically the juxtapositioning of: User requirements (the reason we do this) Users Content Standards bodies (both technical and advocacy) User groups (local advocates as it were) and forums (remote advocates) Conferences, Webinars, other formal connection opportunities Tools (both open and commercial) Vendors and Developers (the providers of those tools) Consultants, trainers, advisors, mentors, etc. Book writers and their vendors I've likely missed some items. A chart that makes sense of this ecosystem at a glance could be very useful to pass around as posters and include in blog posts, etc.. This would contain no detail about DITA itself, but rather highlight the amazing resources and how they relate to the whole. -- Don R. Day Founding Chair, OASIS DITA Technical Committee (current version: DITA 1.3 ) LinkedIn: donrday    Twitter: @donrday About.me: Don R. Day    Skype: don.r.day Where is the wisdom we have lost in knowledge? Where is the knowledge we have lost in information? --T.S. Eliot On 6/21/2016 3:32 PM, Tom Magliery wrote: Regarding the challenge of helping people understand the distinction between DITA and DITA OT , here are some thoughts stemming from training new (to structured authoring) authors, parts of which some people find a little alarming, but all of which I cling to nerdily and stubbornly nevertheless. It starts with separation of structure and formatting. I use this premise to motivate a pair of diagrams, simple enough that I think you can get them from these verbal descriptions:   1. For traditional/DTP , there are two blobs in the diagram, one of which says Authoring tool and has an arrow pointing to the other, which says Output .   2. For structured authoring the Authoring tool blob yields a Structured document , which sits next to another (originless) blob called Style sheets . Both of these blobs feed into another one called Publishing system , which in turn points to the final blob Output .   The mantra I use with these two diagrams is With structured authoring you are not creating output; you are creating input. E.g., you are not saying This stuff should have a box around it and be positioned over that-a-way ; you are only saying This stuff is a sidebar . Then the publishing system says Oh yeah, I know what to do with that.   From there it is an easy step to discussing the following very real process, strongly similar to the code-test-debug cycle in programming:   1. Write some code (XML/content). 2. Generate output. 3. Examine the output for correctness. 4. Fix errors and go to step 2.   I talk of the giddy anticipation when you're about to generate output again, the disappointment when it's still broken, and of course that eventual rush when you finally do get it right.   The fix errors part is a burden potentially shared by both authors and style sheet developers, which does complicate matters. As far as the analogy goes, this can be handwaved a bit by the fact that we are teaching authors about their particular perspective on this ecosystem. But this also gives an opportunity to discuss the negotiations/compromises that sometimes must be made between markup design, markup usage, and style sheet development effort. (Similar negotiations may occur between product management and development in a programming shop, btw.)   I think you could possibly push this analogy further with comparisons between DITA and programming languages, but I have not needed them, or thought them out enough to be sure how well it would work.   While I admit that this analogy may be a little scary to folks who think programming is intimidating, I also think that it helps strengthen the basic premise of separation of structure from formatting that really is fundamental to understanding why DITA <> DITA OT. The cyclical process with write code and generate output in different stages reinforces that they are different parts of the system.   mag   Virus-free. www.avast.com

FWIW: Per my previous comment about depicting the broader DITA Ecosystem, Chet Ensign asked whether I had any existing art, but I did not. Thanks to https://www.text2mindmap.com/ , we can at least see a mind map of this outline (although the infographic I have in mind would show directional dependencies and content flows, where possible): The DITA Standard     The reasons we do this:         User requirements         Users         Content     The support communities:         Standards bodies (both technical and advocacy)         User groups (local advocates as it were) and forums (remote advocates)         Conferences, Webinars, other formal connection opportunities     The enablers:         Open Tools and Developers         Commercial Tools and Vendors         Consultants, trainers, advisors, mentors, etc.     The materials:         The DITA Standard itself         Bloggers and knowledge centers         Book writers and their vendors On 6/21/2016 3:50 PM, Don Day wrote: During the discussion, I was thinking instead of an infographic explainer of The DITA Ecosystem showing graphically the juxtapositioning of: User requirements (the reason we do this) Users Content Standards bodies (both technical and advocacy) User groups (local advocates as it were) and forums (remote advocates) Conferences, Webinars, other formal connection opportunities Tools (both open and commercial) Vendors and Developers (the providers of those tools) Consultants, trainers, advisors, mentors, etc. Book writers and their vendors I've likely missed some items. A chart that makes sense of this ecosystem at a glance could be very useful to pass around as posters and include in blog posts, etc.. This would contain no detail about DITA itself, but rather highlight the amazing resources and how they relate to the whole. -- Don R. Day Founding Chair, OASIS DITA Technical Committee (current version: DITA 1.3 ) LinkedIn: donrday    Twitter: @donrday About.me: Don R. Day    Skype: don.r.day Where is the wisdom we have lost in knowledge? Where is the knowledge we have lost in information? --T.S. Eliot On 6/21/2016 3:32 PM, Tom Magliery wrote: Regarding the challenge of helping people understand the distinction between DITA and DITA OT , here are some thoughts stemming from training new (to structured authoring) authors, parts of which some people find a little alarming, but all of which I cling to nerdily and stubbornly nevertheless. It starts with separation of structure and formatting. I use this premise to motivate a pair of diagrams, simple enough that I think you can get them from these verbal descriptions:   1. For traditional/DTP , there are two blobs in the diagram, one of which says Authoring tool and has an arrow pointing to the other, which says Output .   2. For structured authoring the Authoring tool blob yields a Structured document , which sits next to another (originless) blob called Style sheets . Both of these blobs feed into another one called Publishing system , which in turn points to the final blob Output .   The mantra I use with these two diagrams is With structured authoring you are not creating output; you are creating input. E.g., you are not saying This stuff should have a box around it and be positioned over that-a-way ; you are only saying This stuff is a sidebar . Then the publishing system says Oh yeah, I know what to do with that.   From there it is an easy step to discussing the following very real process, strongly similar to the code-test-debug cycle in programming:   1. Write some code (XML/content). 2. Generate output. 3. Examine the output for correctness. 4. Fix errors and go to step 2.   I talk of the giddy anticipation when you're about to generate output again, the disappointment when it's still broken, and of course that eventual rush when you finally do get it right.   The fix errors part is a burden potentially shared by both authors and style sheet developers, which does complicate matters. As far as the analogy goes, this can be handwaved a bit by the fact that we are teaching authors about their particular perspective on this ecosystem. But this also gives an opportunity to discuss the negotiations/compromises that sometimes must be made between markup design, markup usage, and style sheet development effort. (Similar negotiations may occur between product management and development in a programming shop, btw.)   I think you could possibly push this analogy further with comparisons between DITA and programming languages, but I have not needed them, or thought them out enough to be sure how well it would work.   While I admit that this analogy may be a little scary to folks who think programming is intimidating, I also think that it helps strengthen the basic premise of separation of structure from formatting that really is fundamental to understanding why DITA <> DITA OT. The cyclical process with write code and generate output in different stages reinforces that they are different parts of the system.   mag   Virus-free. www.avast.com -- Don R. Day Founding Chair, OASIS DITA Technical Committee (current version: DITA 1.3 ) LinkedIn: donrday    Twitter: @donrday About.me: Don R. Day    Skype: don.r.day Where is the wisdom we have lost in knowledge? Where is the knowledge we have lost in information? --T.S. Eliot Virus-free. www.avast.com Attachment: DITA Ecosystem.jpg Description: JPEG image

Tom, Awesome example with the diagrams/narrative. Computational Thinking is a term that has been going around in Computer Science education, and that's what I use for my examples as a teach DITA authoring here at Virginia Tech. J. Wing (currently at Microsoft) defines Computational Thinking as the thought processes involved in formulating problems and their solutions so that the solutions are represented in a form that can be effectively carried out by an information-processing agent. She says that the main stages in Computational Thinking are abstraction and automation: you think about the abstractions (algorithms, big-picture ideas) related to a problem, and then, only then you or someone else will automate that process and fix the situation. In my research and teaching work, I see DITA the standard as the method for abstraction (you have to think about your conrefs, your maps, your keys, your topic types) and then the Toolkit or a fancier software app is the automation agent. My students are mostly English majors, so they focus on DITA the standard/abstraction, and then automation happens when they use a tool. We separate the standard from the toolkit with this. Here's a little more about Computational Thinking: https://www.cs.cmu.edu/link/research-notebook-computational-thinking-what-and-why and I also have a paper about my approach to teaching DITA with/through it that was published last year in the IEEE Transactions on Professional Communication and I can share if you are interested.  Best, Carlos - --  Carlos Evia, Ph.D. Director of Professional and Technical Writing Associate Professor of Technical Communication Department of English Center for Human-Computer Interaction Virginia Tech Blacksburg, VA 24061-0112 (540)200-8201 On Jun 21, 2016, at 4:32 PM, Tom Magliery < tom.magliery@justsystems.com > wrote: Regarding the challenge of helping people understand the distinction between DITA and DITA OT , here are some thoughts stemming from training new (to structured authoring) authors, parts of which some people find a little alarming, but all of which I cling to nerdily and stubbornly nevertheless. It starts with separation of structure and formatting. I use this premise to motivate a pair of diagrams, simple enough that I think you can get them from these verbal descriptions:   1. For traditional/DTP , there are two blobs in the diagram, one of which says Authoring tool and has an arrow pointing to the other, which says Output .     2. For structured authoring the Authoring tool blob yields a Structured document , which sits next to another (originless) blob called Style sheets . Both of these blobs feed into another one called Publishing system , which in turn points to the final blob Output .   The mantra I use with these two diagrams is With structured authoring you are not creating output; you are creating input. E.g., you are not saying This stuff should have a box around it and be positioned over that-a-way ; you are only saying This stuff is a sidebar . Then the publishing system says Oh yeah, I know what to do with that.   From there it is an easy step to discussing the following very real process, strongly similar to the code-test-debug cycle in programming:   1. Write some code (XML/content). 2. Generate output. 3. Examine the output for correctness. 4. Fix errors and go to step 2.   I talk of the giddy anticipation when you're about to generate output again, the disappointment when it's still broken, and of course that eventual rush when you finally do get it right.   The fix errors part is a burden potentially shared by both authors and style sheet developers, which does complicate matters. As far as the analogy goes, this can be handwaved a bit by the fact that we are teaching authors about their particular perspective on this ecosystem. But this also gives an opportunity to discuss the negotiations/compromises that sometimes must be made between markup design, markup usage, and style sheet development effort. (Similar negotiations may occur between product management and development in a programming shop, btw.)   I think you could possibly push this analogy further with comparisons between DITA and programming languages, but I have not needed them, or thought them out enough to be sure how well it would work.   While I admit that this analogy may be a little scary to folks who think programming is intimidating, I also think that it helps strengthen the basic premise of separation of structure from formatting that really is fundamental to understanding why DITA <> DITA OT. The cyclical process with write code and generate output in different stages reinforces that they are different parts of the system.   mag

Great post, Tom. I have a very similar graphic that I use while explaining the components of a DITA implementation to clients and prospective clients. Should the DITA TC consider doing a committee note about this? Everyone, please remember that we have the committee note mechanism to provide official communications between the DITA TC and the DITA community -- and this mechanism does not involve any OASIS approval. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 6/21/2016 4:32 PM, Tom Magliery wrote: Regarding the challenge of helping people understand the distinction between DITA and DITA OT , here are some thoughts stemming from training new (to structured authoring) authors, parts of which some people find a little alarming, but all of which I cling to nerdily and stubbornly nevertheless. It starts with separation of structure and formatting. I use this premise to motivate a pair of diagrams, simple enough that I think you can get them from these verbal descriptions:   1. For traditional/DTP , there are two blobs in the diagram, one of which says Authoring tool and has an arrow pointing to the other, which says Output .   2. For structured authoring the Authoring tool blob yields a Structured document , which sits next to another (originless) blob called Style sheets . Both of these blobs feed into another one called Publishing system , which in turn points to the final blob Output .   The mantra I use with these two diagrams is With structured authoring you are not creating output; you are creating input. E.g., you are not saying This stuff should have a box around it and be positioned over that-a-way ; you are only saying This stuff is a sidebar . Then the publishing system says Oh yeah, I know what to do with that.   From there it is an easy step to discussing the following very real process, strongly similar to the code-test-debug cycle in programming:   1. Write some code (XML/content). 2. Generate output. 3. Examine the output for correctness. 4. Fix errors and go to step 2.   I talk of the giddy anticipation when you're about to generate output again, the disappointment when it's still broken, and of course that eventual rush when you finally do get it right.   The fix errors part is a burden potentially shared by both authors and style sheet developers, which does complicate matters. As far as the analogy goes, this can be handwaved a bit by the fact that we are teaching authors about their particular perspective on this ecosystem. But this also gives an opportunity to discuss the negotiations/compromises that sometimes must be made between markup design, markup usage, and style sheet development effort. (Similar negotiations may occur between product management and development in a programming shop, btw.)   I think you could possibly push this analogy further with comparisons between DITA and programming languages, but I have not needed them, or thought them out enough to be sure how well it would work.   While I admit that this analogy may be a little scary to folks who think programming is intimidating, I also think that it helps strengthen the basic premise of separation of structure from formatting that really is fundamental to understanding why DITA <> DITA OT. The cyclical process with write code and generate output in different stages reinforces that they are different parts of the system.   mag  

Sounds like a good idea to me! I support the creation of a committee note.   Thanks and best regards,   --Scott   Scott Hudson Content Strategist Training & Documentation Global Services & Support Jeppesen     Digital Aviation     Boeing Jeppesen email: scott.hudson@jeppesen.com 55 Inverness Drive East Englewood, CO 80112 www.jeppesen.com   From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Kristen James Eberlein Sent: Wednesday, June 22, 2016 8:11 AM To: dita@lists.oasis-open.org Subject: Re: [dita] Understanding DITA vs. DITA OT   Great post, Tom. I have a very similar graphic that I use while explaining the components of a DITA implementation to clients and prospective clients. Should the DITA TC consider doing a committee note about this? Everyone, please remember that we have the committee note mechanism to provide official communications between the DITA TC and the DITA community -- and this mechanism does not involve any OASIS approval. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 6/21/2016 4:32 PM, Tom Magliery wrote: Regarding the challenge of helping people understand the distinction between "DITA" and "DITA OT", here are some thoughts stemming from training new (to structured authoring) authors, parts of which some people find a little alarming, but all of which I cling to nerdily and stubbornly nevertheless. It starts with separation of structure and formatting. I use this premise to motivate a pair of diagrams, simple enough that I think you can get them from these verbal descriptions:   1. For "traditional/DTP", there are two blobs in the diagram, one of which says "Authoring tool" and has an arrow pointing to the other, which says "Output".   2. For "structured authoring" the "Authoring tool" blob yields a "Structured document", which sits next to another (originless) blob called "Style sheets". Both of these blobs feed into another one called "Publishing system", which in turn points to the final blob "Output".   The mantra I use with these two diagrams is "With structured authoring you are not creating output; you are creating input." E.g., you are not saying "This stuff should have a box around it and be positioned over that-a-way"; you are only saying "This stuff is a sidebar". Then the publishing system says "Oh yeah, I know what to do with that."   From there it is an easy step to discussing the following very real process, strongly similar to the code-test-debug cycle in programming:   1. Write some code (XML/content). 2. Generate output. 3. Examine the output for correctness. 4. Fix errors and go to step 2.   I talk of the giddy anticipation when you're about to generate output again, the disappointment when it's still broken, and of course that eventual rush when you finally do get it right.   The "fix errors" part is a burden potentially shared by both authors and style sheet developers, which does complicate matters. As far as the analogy goes, this can be handwaved a bit by the fact that we are teaching authors about their particular perspective on this ecosystem. But this also gives an opportunity to discuss the negotiations/compromises that sometimes must be made between markup design, markup usage, and style sheet development effort. (Similar negotiations may occur between product management and development in a programming shop, btw.)   I think you could possibly push this analogy further with comparisons between DITA and programming languages, but I have not needed them, or thought them out enough to be sure how well it would work.   While I admit that this analogy may be a little scary to folks who think programming is intimidating, I also think that it helps strengthen the basic premise of separation of structure from formatting that really is fundamental to understanding why DITA <> DITA OT. The cyclical process with "write code" and "generate output" in different stages reinforces that they are different parts of the system.   mag     --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

As the person perhaps most squarely stuck in the middle of the two groups, I sketched out my thoughts on how DITA and DITA-OT overlap, or not. I drafted this before Kris suggested the committee note, but held off sharing for a few days because I spent waaaay too much time thinking about edits. Clearly these are my own thoughts, not the official position of either OASIS or DITA-OT: http://metadita.org/toolkit/ditaversusditaot.html I also agree that a committee note would be useful as a way to get more attention on this, and to have a handy link for anybody who gets this question (we're not going to stop getting this question any time soon). Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---06/22/2016 09:12:16 AM---Great post, Tom. I have a very similar graphic that I use while explaining the components of a DITA From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org Date: 06/22/2016 09:12 AM Subject: Re: [dita] Understanding DITA vs. DITA OT Sent by: <dita@lists.oasis-open.org> Great post, Tom. I have a very similar graphic that I use while explaining the components of a DITA implementation to clients and prospective clients. Should the DITA TC consider doing a committee note about this? Everyone, please remember that we have the committee note mechanism to provide official communications between the DITA TC and the DITA community -- and this mechanism does not involve any OASIS approval. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 6/21/2016 4:32 PM, Tom Magliery wrote: Regarding the challenge of helping people understand the distinction between "DITA" and "DITA OT", here are some thoughts stemming from training new (to structured authoring) authors, parts of which some people find a little alarming, but all of which I cling to nerdily and stubbornly nevertheless. It starts with separation of structure and formatting. I use this premise to motivate a pair of diagrams, simple enough that I think you can get them from these verbal descriptions:   1. For "traditional/DTP", there are two blobs in the diagram, one of which says "Authoring tool" and has an arrow pointing to the other, which says "Output".   2. For "structured authoring" the "Authoring tool" blob yields a "Structured document", which sits next to another (originless) blob called "Style sheets". Both of these blobs feed into another one called "Publishing system", which in turn points to the final blob "Output".   The mantra I use with these two diagrams is "With structured authoring you are not creating output; you are creating input." E.g., you are not saying "This stuff should have a box around it and be positioned over that-a-way"; you are only saying "This stuff is a sidebar". Then the publishing system says "Oh yeah, I know what to do with that."   From there it is an easy step to discussing the following very real process, strongly similar to the code-test-debug cycle in programming:   1. Write some code (XML/content). 2. Generate output. 3. Examine the output for correctness. 4. Fix errors and go to step 2.   I talk of the giddy anticipation when you're about to generate output again, the disappointment when it's still broken, and of course that eventual rush when you finally do get it right.   The "fix errors" part is a burden potentially shared by both authors and style sheet developers, which does complicate matters. As far as the analogy goes, this can be handwaved a bit by the fact that we are teaching authors about their particular perspective on this ecosystem. But this also gives an opportunity to discuss the negotiations/compromises that sometimes must be made between markup design, markup usage, and style sheet development effort. (Similar negotiations may occur between product management and development in a programming shop, btw.)   I think you could possibly push this analogy further with comparisons between DITA and programming languages, but I have not needed them, or thought them out enough to be sure how well it would work.   While I admit that this analogy may be a little scary to folks who think programming is intimidating, I also think that it helps strengthen the basic premise of separation of structure from formatting that really is fundamental to understanding why DITA <> DITA OT. The cyclical process with "write code" and "generate output" in different stages reinforces that they are different parts of the system.   mag   --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

I kinda feel as if there can't be an article that talks about the relationship between these two things that does not have the term de facto in it somewhere.   mag       From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Robert D Anderson Sent: Monday, June 27, 2016 8:54 AM To: dita@lists.oasis-open.org Subject: Re: [dita] Understanding DITA vs. DITA OT   As the person perhaps most squarely stuck in the middle of the two groups, I sketched out my thoughts on how DITA and DITA-OT overlap, or not. I drafted this before Kris suggested the committee note, but held off sharing for a few days because I spent waaaay too much time thinking about edits. Clearly these are my own thoughts, not the official position of either OASIS or DITA-OT: http://metadita.org/toolkit/ditaversusditaot.html I also agree that a committee note would be useful as a way to get more attention on this, and to have a handy link for anybody who gets this question (we're not going to stop getting this question any time soon). Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---06/22/2016 09:12:16 AM---Great post, Tom. I have a very similar graphic that I use while explaining the components of a DITA From: Kristen James Eberlein < kris@eberleinconsulting.com > To: dita@lists.oasis-open.org Date: 06/22/2016 09:12 AM Subject: Re: [dita] Understanding DITA vs. DITA OT Sent by: < dita@lists.oasis-open.org > Great post, Tom. I have a very similar graphic that I use while explaining the components of a DITA implementation to clients and prospective clients. Should the DITA TC consider doing a committee note about this? Everyone, please remember that we have the committee note mechanism to provide official communications between the DITA TC and the DITA community -- and this mechanism does not involve any OASIS approval. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 6/21/2016 4:32 PM, Tom Magliery wrote: Regarding the challenge of helping people understand the distinction between "DITA" and "DITA OT", here are some thoughts stemming from training new (to structured authoring) authors, parts of which some people find a little alarming, but all of which I cling to nerdily and stubbornly nevertheless. It starts with separation of structure and formatting. I use this premise to motivate a pair of diagrams, simple enough that I think you can get them from these verbal descriptions:   1. For "traditional/DTP", there are two blobs in the diagram, one of which says "Authoring tool" and has an arrow pointing to the other, which says "Output".   2. For "structured authoring" the "Authoring tool" blob yields a "Structured document", which sits next to another (originless) blob called "Style sheets". Both of these blobs feed into another one called "Publishing system", which in turn points to the final blob "Output".   The mantra I use with these two diagrams is "With structured authoring you are not creating output; you are creating input." E.g., you are not saying "This stuff should have a box around it and be positioned over that-a-way"; you are only saying "This stuff is a sidebar". Then the publishing system says "Oh yeah, I know what to do with that."   From there it is an easy step to discussing the following very real process, strongly similar to the code-test-debug cycle in programming:   1. Write some code (XML/content). 2. Generate output. 3. Examine the output for correctness. 4. Fix errors and go to step 2.   I talk of the giddy anticipation when you're about to generate output again, the disappointment when it's still broken, and of course that eventual rush when you finally do get it right.   The "fix errors" part is a burden potentially shared by both authors and style sheet developers, which does complicate matters. As far as the analogy goes, this can be handwaved a bit by the fact that we are teaching authors about their particular perspective on this ecosystem. But this also gives an opportunity to discuss the negotiations/compromises that sometimes must be made between markup design, markup usage, and style sheet development effort. (Similar negotiations may occur between product management and development in a programming shop, btw.)   I think you could possibly push this analogy further with comparisons between DITA and programming languages, but I have not needed them, or thought them out enough to be sure how well it would work.   While I admit that this analogy may be a little scary to folks who think programming is intimidating, I also think that it helps strengthen the basic premise of separation of structure from formatting that really is fundamental to understanding why DITA <> DITA OT. The cyclical process with "write code" and "generate output" in different stages reinforces that they are different parts of the system.   mag   --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

Hi, Robert, I like your piece, but think the first diagram, of DITA and DITA-OT not touching each other, might need to have some intersection to represent the grammar files, which are in both of them.  I think that it is having the identical grammar files in both, organized in a set of analogous structures, that sometimes confuses folks about the relationship between the two. just my $.02. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Mon, Jun 27, 2016 at 8:54 AM, Robert D Anderson < robander@us.ibm.com > wrote: As the person perhaps most squarely stuck in the middle of the two groups, I sketched out my thoughts on how DITA and DITA-OT overlap, or not. I drafted this before Kris suggested the committee note, but held off sharing for a few days because I spent waaaay too much time thinking about edits. Clearly these are my own thoughts, not the official position of either OASIS or DITA-OT: http://metadita.org/toolkit/ditaversusditaot.html I also agree that a committee note would be useful as a way to get more attention on this, and to have a handy link for anybody who gets this question (we're not going to stop getting this question any time soon). Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---06/22/2016 09:12:16 AM---Great post, Tom. I have a very similar graphic that I use while explaining the components of a DITA From: Kristen James Eberlein < kris@eberleinconsulting.com > To: dita@lists.oasis-open.org Date: 06/22/2016 09:12 AM Subject: Re: [dita] Understanding DITA vs. DITA OT Sent by: < dita@lists.oasis-open.org > Great post, Tom. I have a very similar graphic that I use while explaining the components of a DITA implementation to clients and prospective clients. Should the DITA TC consider doing a committee note about this? Everyone, please remember that we have the committee note mechanism to provide official communications between the DITA TC and the DITA community -- and this mechanism does not involve any OASIS approval. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 6/21/2016 4:32 PM, Tom Magliery wrote: Regarding the challenge of helping people understand the distinction between "DITA" and "DITA OT", here are some thoughts stemming from training new (to structured authoring) authors, parts of which some people find a little alarming, but all of which I cling to nerdily and stubbornly nevertheless. It starts with separation of structure and formatting. I use this premise to motivate a pair of diagrams, simple enough that I think you can get them from these verbal descriptions:   1. For "traditional/DTP", there are two blobs in the diagram, one of which says "Authoring tool" and has an arrow pointing to the other, which says "Output".   2. For "structured authoring" the "Authoring tool" blob yields a "Structured document", which sits next to another (originless) blob called "Style sheets". Both of these blobs feed into another one called "Publishing system", which in turn points to the final blob "Output".   The mantra I use with these two diagrams is "With structured authoring you are not creating output; you are creating input." E.g., you are not saying "This stuff should have a box around it and be positioned over that-a-way"; you are only saying "This stuff is a sidebar". Then the publishing system says "Oh yeah, I know what to do with that."   From there it is an easy step to discussing the following very real process, strongly similar to the code-test-debug cycle in programming:   1. Write some code (XML/content). 2. Generate output. 3. Examine the output for correctness. 4. Fix errors and go to step 2.   I talk of the giddy anticipation when you're about to generate output again, the disappointment when it's still broken, and of course that eventual rush when you finally do get it right.   The "fix errors" part is a burden potentially shared by both authors and style sheet developers, which does complicate matters. As far as the analogy goes, this can be handwaved a bit by the fact that we are teaching authors about their particular perspective on this ecosystem. But this also gives an opportunity to discuss the negotiations/compromises that sometimes must be made between markup design, markup usage, and style sheet development effort. (Similar negotiations may occur between product management and development in a programming shop, btw.)   I think you could possibly push this analogy further with comparisons between DITA and programming languages, but I have not needed them, or thought them out enough to be sure how well it would work.   While I admit that this analogy may be a little scary to folks who think programming is intimidating, I also think that it helps strengthen the basic premise of separation of structure from formatting that really is fundamental to understanding why DITA <> DITA OT. The cyclical process with "write code" and "generate output" in different stages reinforces that they are different parts of the system.   mag   --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php