OASIS Darwin Information Typing Architecture (DITA) TC

Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) Attachment: shortdesc_article 2.pdf Description: Adobe PDF document

The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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

FYI. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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

Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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

Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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

Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity. Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago. I also agree with Nancy's comments. Best Regards, Bob Thomas On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

Hi Bob, I think shortdescs are normally rendered in PDF, as well as HTML. For what it's worth the design intent for shortdescs at the time of their addition to the language was to implement the "thesis sentence" principle of the STOP methodology, where the first sentence of a topic provides its thesis/key point. This "thesis sentence" is then also useful as a search result preview etc. but its first and primary purpose is to be the first sentence of the topic. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Bob Thomas <bob.thomas@tagsmiths.com> To:         Nancy Harrison <nharrison@infobridge-solutions.com> Cc:         Kristen James Eberlein <kris@eberleinconsulting.com>, "dita-adoption@lists.oasis-open.org" <dita-adoption@lists.oasis-open.org> Date:         02/29/2016 10:24 AM Subject:         Re: [dita-adoption] Fwd: Re: [dita] Adoption Committee whitepapers Sent by:         <dita-adoption@lists.oasis-open.org> Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity. Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago. I also agree with Nancy's comments. Best Regards, Bob Thomas On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

As another long-timer with the design, I've also understood and taught the use of the shortdesc as a first paragraph in all instances, with special behaviors. I don't care if my credit card quote is used; in the blog post where I first used the allusion, it was meant to imply a loyalty program--if you use it consistently, you reap rewards throughout the life cycle of your topics. Let it go if it doesn't fit. Still, my own recommendation is always  to use it since any lesser recommendation encourages some to not use it, with potentially very costly rework down the road once the rewards of membership do start to become apparent. That is all. -- Don On 2/29/2016 9:46 AM, Michael Priestley wrote: Hi Bob, I think shortdescs are normally rendered in PDF, as well as HTML. For what it's worth the design intent for shortdescs at the time of their addition to the language was to implement the thesis sentence principle of the STOP methodology, where the first sentence of a topic provides its thesis/key point. This thesis sentence is then also useful as a search result preview etc. but its first and primary purpose is to be the first sentence of the topic. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Bob Thomas <bob.thomas@tagsmiths.com> To:         Nancy Harrison <nharrison@infobridge-solutions.com> Cc:         Kristen James Eberlein <kris@eberleinconsulting.com> , dita-adoption@lists.oasis-open.org <dita-adoption@lists.oasis-open.org> Date:         02/29/2016 10:24 AM Subject:         Re: [dita-adoption] Fwd: Re: [dita] Adoption Committee whitepapers Sent by:         <dita-adoption@lists.oasis-open.org> Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity. Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago. I also agree with Nancy's comments. Best Regards, Bob Thomas On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ( How and When Shortdescs appear )  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as What do you use a Shortdesc for?   Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) -- Don R. Day Founding Chair, OASIS DITA Technical Committee 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 This email has been sent from a virus-free computer protected by Avast. www.avast.com

It turns out that the January 25th iteration of the shortdesc article never made it to Kavi. It is there now along with its DITA source. Please accept my apologies for part that I played in this confusion. Best Regards, Bob Thomas On Mon, Feb 29, 2016 at 9:20 AM, Don Day < donday@donrday.com > wrote: As another long-timer with the design, I've also understood and taught the use of the shortdesc as a first paragraph in all instances, with special behaviors. I don't care if my credit card quote is used; in the blog post where I first used the allusion, it was meant to imply a loyalty program--if you use it consistently, you reap rewards throughout the life cycle of your topics. Let it go if it doesn't fit. Still, my own recommendation is always  to use it since any lesser recommendation encourages some to not use it, with potentially very costly rework down the road once the "rewards of membership" do start to become apparent. That is all. -- Don On 2/29/2016 9:46 AM, Michael Priestley wrote: Hi Bob, I think shortdescs are normally rendered in PDF, as well as HTML. For what it's worth the design intent for shortdescs at the time of their addition to the language was to implement the "thesis sentence" principle of the STOP methodology, where the first sentence of a topic provides its thesis/key point. This "thesis sentence" is then also useful as a search result preview etc. but its first and primary purpose is to be the first sentence of the topic. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Bob Thomas <bob.thomas@tagsmiths.com> To:         Nancy Harrison <nharrison@infobridge-solutions.com> Cc:         Kristen James Eberlein <kris@eberleinconsulting.com> , "dita-adoption@lists.oasis-open.org" <dita-adoption@lists.oasis-open.org> Date:         02/29/2016 10:24 AM Subject:         Re: [dita-adoption] Fwd: Re: [dita] Adoption Committee whitepapers Sent by:         <dita-adoption@lists.oasis-open.org> Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity. Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago. I also agree with Nancy's comments. Best Regards, Bob Thomas On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) -- Don R. Day Founding Chair, OASIS DITA Technical Committee 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 This email has been sent from a virus-free computer protected by Avast. www.avast.com -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

Thanks, Bob!   Joe Storbeck Senior Structured Data Analyst  



1717 Universal City Blvd Universal City, TX 78148 Phone: (512) 438-9457 Fax: (210) 616-0088 e-mail: jstorbeck@janacorp.com JANA, Inc. is an Equal Opportunity Employer. If you have received this e-mail by mistake please inform us and destroy this e-mail and any documents it might contain.   From: dita-adoption@lists.oasis-open.org [mailto:dita-adoption@lists.oasis-open.org] On Behalf Of Bob Thomas Sent: Monday, February 29, 2016 11:38 AM To: Don Day Cc: dita-adoption@lists.oasis-open.org Subject: Re: [dita-adoption] Fwd: Re: [dita] Adoption Committee whitepapers   It turns out that the January 25th iteration of the shortdesc article never made it to Kavi. It is there now along with its DITA source. Please accept my apologies for part that I played in this confusion.   Best Regards, Bob Thomas   On Mon, Feb 29, 2016 at 9:20 AM, Don Day < donday@donrday.com > wrote: As another long-timer with the design, I've also understood and taught the use of the shortdesc as a first paragraph in all instances, with special behaviors. I don't care if my credit card quote is used; in the blog post where I first used the allusion, it was meant to imply a loyalty program--if you use it consistently, you reap rewards throughout the life cycle of your topics. Let it go if it doesn't fit. Still, my own recommendation is always  to use it since any lesser recommendation encourages some to not use it, with potentially very costly rework down the road once the "rewards of membership" do start to become apparent. That is all. -- Don   On 2/29/2016 9:46 AM, Michael Priestley wrote: Hi Bob, I think shortdescs are normally rendered in PDF, as well as HTML. For what it's worth the design intent for shortdescs at the time of their addition to the language was to implement the "thesis sentence" principle of the STOP methodology, where the first sentence of a topic provides its thesis/key point. This "thesis sentence" is then also useful as a search result preview etc. but its first and primary purpose is to be the first sentence of the topic. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Bob Thomas <bob.thomas@tagsmiths.com> To:         Nancy Harrison <nharrison@infobridge-solutions.com> Cc:         Kristen James Eberlein <kris@eberleinconsulting.com> , "dita-adoption@lists.oasis-open.org" <dita-adoption@lists.oasis-open.org> Date:         02/29/2016 10:24 AM Subject:         Re: [dita-adoption] Fwd: Re: [dita] Adoption Committee whitepapers Sent by:         <dita-adoption@lists.oasis-open.org> Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity. Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago. I also agree with Nancy's comments. Best Regards, Bob Thomas On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)   -- Don R. Day Founding Chair, OASIS DITA Technical Committee 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   This email has been sent from a virus-free computer protected by Avast. www.avast.com   -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)  

Agreed, thank you Bob! I was a bit confused at some of the comments that were circulating earlier today as I knew we had made changes some time ago that took care of most if not all of items that were brought up. Bob was very generous with his time and Joe and I went through a few additional edits rounds with Bob on this material. I believe Don's quote is still there. That was from Joe's first draft, but I certainly understood the intent and am somewhat puzzled at how else it could be taken. Cheers!  Keith Schengili-Roberts DITA Information Architect / DITA Specialist   IXIASOFT  825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1 tel  + 1 514 279-4942  /  toll free + 1 877 279-4942 cell + 1 647-472-7367  robertsk@ixiasoft.com  /  www.ixiasoft.com   From: dita-adoption@lists.oasis-open.org <dita-adoption@lists.oasis-open.org> on behalf of Bob Thomas <bob.thomas@tagsmiths.com> Sent: Monday, February 29, 2016 12:38 PM To: Don Day Cc: dita-adoption@lists.oasis-open.org Subject: Re: [dita-adoption] Fwd: Re: [dita] Adoption Committee whitepapers   It turns out that the January 25th iteration of the shortdesc article never made it to Kavi. It is there now along with its DITA source. Please accept my apologies for part that I played in this confusion. Best Regards, Bob Thomas On Mon, Feb 29, 2016 at 9:20 AM, Don Day < donday@donrday.com > wrote: As another long-timer with the design, I've also understood and taught the use of the shortdesc as a first paragraph in all instances, with special behaviors. I don't care if my credit card quote is used; in the blog post where I first used the allusion, it was meant to imply a loyalty program--if you use it consistently, you reap rewards throughout the life cycle of your topics. Let it go if it doesn't fit. Still, my own recommendation is always  to use it since any lesser recommendation encourages some to not use it, with potentially very costly rework down the road once the "rewards of membership" do start to become apparent. That is all. -- Don On 2/29/2016 9:46 AM, Michael Priestley wrote: Hi Bob, I think shortdescs are normally rendered in PDF, as well as HTML. For what it's worth the design intent for shortdescs at the time of their addition to the language was to implement the "thesis sentence" principle of the STOP methodology, where the first sentence of a topic provides its thesis/key point. This "thesis sentence" is then also useful as a search result preview etc. but its first and primary purpose is to be the first sentence of the topic. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Bob Thomas <bob.thomas@tagsmiths.com> To:         Nancy Harrison <nharrison@infobridge-solutions.com> Cc:         Kristen James Eberlein <kris@eberleinconsulting.com> , "dita-adoption@lists.oasis-open.org" <dita-adoption@lists.oasis-open.org> Date:         02/29/2016 10:24 AM Subject:         Re: [dita-adoption] Fwd: Re: [dita] Adoption Committee whitepapers Sent by:         <dita-adoption@lists.oasis-open.org> Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity. Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago. I also agree with Nancy's comments. Best Regards, Bob Thomas On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) -- Don R. Day Founding Chair, OASIS DITA Technical Committee 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 This email has been sent from a virus-free computer protected by Avast. www.avast.com -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

Just to be sure --- Please put me in the the camp of the content of the shortdesc SHOULD be rendered in the output, per the normative statement in the spec: The content of the <shortdesc> element SHOULD be rendered as the initial paragraph of the topic. http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/base/shortdesc.html#shortdesc Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 2/29/2016 11:20 AM, Don Day wrote: As another long-timer with the design, I've also understood and taught the use of the shortdesc as a first paragraph in all instances, with special behaviors. I don't care if my credit card quote is used; in the blog post where I first used the allusion, it was meant to imply a loyalty program--if you use it consistently, you reap rewards throughout the life cycle of your topics. Let it go if it doesn't fit. Still, my own recommendation is always  to use it since any lesser recommendation encourages some to not use it, with potentially very costly rework down the road once the rewards of membership do start to become apparent. That is all. -- Don On 2/29/2016 9:46 AM, Michael Priestley wrote: Hi Bob, I think shortdescs are normally rendered in PDF, as well as HTML. For what it's worth the design intent for shortdescs at the time of their addition to the language was to implement the thesis sentence principle of the STOP methodology, where the first sentence of a topic provides its thesis/key point. This thesis sentence is then also useful as a search result preview etc. but its first and primary purpose is to be the first sentence of the topic. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Bob Thomas <bob.thomas@tagsmiths.com> To:         Nancy Harrison <nharrison@infobridge-solutions.com> Cc:         Kristen James Eberlein <kris@eberleinconsulting.com> , dita-adoption@lists.oasis-open.org <dita-adoption@lists.oasis-open.org> Date:         02/29/2016 10:24 AM Subject:         Re: [dita-adoption] Fwd: Re: [dita] Adoption Committee whitepapers Sent by:         <dita-adoption@lists.oasis-open.org> Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity. Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago. I also agree with Nancy's comments. Best Regards, Bob Thomas On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ( How and When Shortdescs appear )  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as What do you use a Shortdesc for?   Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) -- Don R. Day Founding Chair, OASIS DITA Technical Committee 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 This email has been sent from a virus-free computer protected by Avast. www.avast.com

As far as I'm concerned, I have always urged teams to include the short descriptions as synopses of the topic. It's critical information  and should be displayed. Writers object because they don't know how to write them. Then they use trivial examples of topics like turning off the machine, topics that shouldn't be written in the first place if they contain no needed information.  JoAnn Sent from my iPhone JoAnn Hackos Comtech Services, Inc. Join The Center for Information-Development Management at the Content Management Strategies/DITA North America Conference on  April 4-6, 2016 . More information at:  https://cm-strategies.com On Feb 29, 2016, at 8:24 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity. Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago. I also agree with Nancy's comments. Best Regards, Bob Thomas On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

I cannot figure out what you are all saying. You believe that short descriptions belong in he topics, not just the ones that are in this article? Is that the conclusion because you don't like these short descriptions?  Please look at the correct draft before making any more comments about the old draft. JoAnn Sent from my iPad JoAnn Hackos President Comtech Services Inc 710 Kipling Street Suite 400 Lakewood CO 80215 303-232-7586   Join The Center for Information-Development Management at the Content Management Strategies/DITA North America Conference on  April 4-6, 2016 . More information at: https://cm-strategies.com On Feb 29, 2016, at 8:24 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity. Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago. I also agree with Nancy's comments. Best Regards, Bob Thomas On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi, The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review. Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) --------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

I fear that the whitepaper is ambiguous on the role of the short description as both content and metadata. Or more specifically as content first and metadata second. The previous specification lays it out fairly clearly:   The DITA 1.2 specification states that the short description is “the initial paragraph-like content …” and “… is also intended to be used as a link preview and for searching.” In fact, “In cases where a topic contains only one paragraph, then it is preferable to include this text in the <shortdesc> and leave the topic body empty.”   In my opinion, the most important role of the short description is support the title of the topic to help the author focus on the subject of the topic. If the title does not require any support to describe the subject of the topic, then the topic does not require a short description.   Cheers,   Rob Hanna, ECMs President & Chief Information Architect Tel +1 (416) 723-4183 Skype singlesourceror   Get our AIIM industry whitepaper at http://www.precisioncontent.com/whitepaper/ .   This email and any files transmitted with it are confidential and intended solely for the use of the individual or entity to whom they are addressed. If you are not the intended recipient you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this information is strictly prohibited. Please notify us by return email if you have received this email in error. ©2016, Precision Content Authoring Solutions Inc, Mississauga, Ontario, Canada       From: dita-adoption@lists.oasis-open.org [mailto:dita-adoption@lists.oasis-open.org] On Behalf Of Joann Hackos Sent: March 1, 2016 9:47 AM To: Bob Thomas <bob.thomas@tagsmiths.com>; Michael Priestley <mpriestl@ca.ibm.com> Cc: Nancy Harrison <nharrison@infobridge-solutions.com>; Kristen James Eberlein <kris@eberleinconsulting.com>; dita-adoption@lists.oasis-open.org; Don R Day <donday@donrday.com> Subject: Re: [dita-adoption] Fwd: Re: [dita] Adoption Committee whitepapers   I cannot figure out what you are all saying. You believe that short descriptions belong in he topics, not just the ones that are in this article? Is that the conclusion because you don't like these short descriptions?    Please look at the correct draft before making any more comments about the old draft. JoAnn Sent from my iPad JoAnn Hackos President Comtech Services Inc 710 Kipling Street Suite 400 Lakewood CO 80215 303-232-7586   Join The Center for Information-Development Management at the Content Management Strategies/DITA North America Conference on  April 4-6, 2016 . More information at: https://cm-strategies.com On Feb 29, 2016, at 8:24 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: Evidently, I have misunderstood the purpose of shortdesc since I first began using DITA 10 years ago. I apologize to the group for my misunderstanding. Because of it, I have been adding confusion rather than clarity.   Given that shortdesc shouldn't be in the PDF, then it shouldn't be rendered as topic content in the HTML either because to do so would result in the HTML and PDF topic content diverging in single source scenarios. Instead, shortdesc should be used for out-of-flow purposes such as link preview text. I assume that the same thing is also true for abstract. Stating the out-of-flow intention unambiguously at the beginning of the article would help others avoid the false conclusions I came to 10 years ago.   I also agree with Nancy's comments.   Best Regards, Bob Thomas   On Sun, Feb 28, 2016 at 11:59 PM, Nancy Harrison < nharrison@infobridge-solutions.com > wrote: Another comment on the shortdesc white paper (besides agreeing with Kris that the shortdescs for the white paper topics shouldn't be ending up in the PDF).  It seems to me that the organization of the paper is a bit counter-intuitive.  That is, I think the section describing how the content in shordescs ends up being displayed in output ("How and When Shortdescs appear")  would be better appearing right near the beginning of the article, not in the middle.  I would think a users primary question about the element is 'what on earth is it for?'  So describing how/where people use it should come right at the beginning, then it makes more sense to look at the guidel;ines for how to construct it.  To that effect, I'd also name it differently, for example as "What do you use a Shortdesc for?"  Unless readers have a sense of what it's going to accomplish, and the usage is what gives them that clue, the guidelines have no context. And, one more thing, I don't understand Don's quote about shortdescs and credit cards; if I don't get it, I'm guessing that many other people won't either... There's a lot of good information in the article, but I do think it needs a bit more work. Nancy _____________ Nancy Harrison Infobridge Solutions  nharrison@infobridge-solutions.com   On Sun, Feb 28, 2016 at 8:08 AM, Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Just to make sure that the Adoption TC saw this also.   Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) -------- Forwarded Message -------- Subject: Re: [dita] Adoption Committee whitepapers Date: Tue, 22 Dec 2015 08:19:40 -0500 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org   The PDF is ... a little bizarre. The topics seems to have a shortdesc that was perhaps just intended to be authoring notes? And intended to be filtered out? For example: Good Short Descriptions = Better Search Engine Results for Online Documents Demonstrates how short descriptions appear within search engine results, and how they can enhance Search Engine Optimization (SEO). Short descriptions appear in search engine results. Well-written short descriptions lets a search engine know that the information it seeks is in your document. When a short description is absent, by default the first sentence or two appears in its place, which rarely summarizes what the content of a topic is about. Conclusion Summing up why short descriptions are a good idea. Though <shortdesc> is an optional element, when used effectively it is a useful guide to readers and content creators alike. When done well, short descriptions tell the reader why they might want to read the content of a given topic, and can help content creators decide which topic is appropriate for reuse. I don't think this is ready for prime time. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype) On 12/21/2015 8:41 PM, Bob Thomas wrote: Hi,   The shortdesc whitepaper is out for second draft review. This first draft went out before the Adoption Committee began using the current review process. For many of you, this will be the first that you have heard about the shortdesc whitepaper. Therefore, I have attached it, and I invite you to review it. A whitepaper describing help features is in the works. Tony self and Stan Doherty are doing a subject matter expert reading of it. Once they are done, the whitepaper will go out for first draft review.   Best Regards, -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)   --------------------------------------------------------------------- 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     --------------------------------------------------------------------- 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     -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)