OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Fwd: Comments on the DITA TC charter


Comments from Gershon and Dawn about the charter

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)




-------- Forwarded Message --------
Subject: RE: Comments on the DITA TC charter
Date: Mon, 11 Jan 2021 14:41:06 +0000
From: Dawn Stevens <dawn.stevens@Comtech-serv.com>
To: Gershon Joseph <gershon@precisioncontent.com>, Wegmann, Frank <Frank.Wegmann@softwareag.com>, Kristen James Eberlein <kris@eberleinconsulting.com>, Nancy Harrison <nharrison@infobridge-solutions.com>


Thanks Gershon. I have added notes to your comments and have my own comments below.

 

My largest comment is that that the charter intersperses a lot of DITA definitions and benefits in sections that are titled Purpose and Scope. I think the Purpose is the purpose of the TC, not DITA and Scope is the scope of work of the TC not the scope of DITA. I suggest separating out a section that defines the standard the TC supports and keeping the Purpose and Scope clearly focused on why the TC exists (to define and maintain) and the tasks that we complete (as defined in the task list). Specifically, I suggest moving and rewriting everything after the first paragraph in Purpose and paragraphs 2, 3, and 4 in Scope into a Standard Definition section. I also think paragraph 5 in Scope (referencing IBM) should be part of the purpose, not the scope.

 

Other questions/comments:

Does the separation of base DITA from other specializations of DITA need to be incorporated into this somehow to establish the scope of what the committee does?

 

Should responsibilities of the TC include appointing people as liaisons to more than just the Adoption TC? Something like, to form and liaise with subcommittees as needed? We have liaisons to the lightweight DITA committee for example. We have had numerous other subcommittees, such as Learning and Training. It seems that the charter should indicate a more general statement about our forming, management, and dissolving of subcommittees.

 

Most charters of this sort I’m familiar with have a section on membership, voting rules, etc. Some of that information is covered in the original call for membership so I suppose technically through the link it is covered, but would it be harmful to include it directly?

 

I am interested in discussing the anticipated audience because I feel that we often discount the needs of the last bullet when discussing the spec, its contents, and its organization.

 

From: Gershon Joseph <gershon@precisioncontent.com>
Sent: Sunday, January 10, 2021 9:10 AM
To: Wegmann, Frank <Frank.Wegmann@softwareag.com>; Dawn Stevens <dawn.stevens@Comtech-serv.com>; Kristen James Eberlein <kris@eberleinconsulting.com>; Nancy Harrison <nharrison@infobridge-solutions.com>
Subject: Comments on the DITA TC charter

 

Hi all,

 

Here are my initial thoughts from my review of the charter:

 

In section “Statement of Purpose” in the list of items introduced by “More specific semantics allow”, I wonder if we should add a list item that talks to keys and a list item that talks to specialization and constraints? Agree that the list should be expanded. I would suggest not keys specifically, but reusability in general (direct and indirect) and I agree that specialization and constraints should be discussed. My question, per my first comment, is simply where should this list go.

 

In the list item introduced by “The work of this TC will differ from similar efforts such as DocBook because of” I think we need to rethink this. The second list item “more specific scope, inasmuch as DITA applies to topic-oriented information rather than all technical manuals” is too limiting, no? Why limit ourselves to topic-oriented information? I’m using DITA at many clients for microcontent and content models that need not be thought of as topics.

In this list, we fail to mention the most obvious difference between DocBook and DITA. DocBook by design intends to deliver a content model to be used as-is. If you modify DocBook, it’s no longer DocBook. On the other hand, DITA is intended to be modified and not intended to be used out of the box. Perhaps we should add this in?  I agree this is true. I question the content on a more basic scale – why does it matter how our work differs from DocBook? Ultimately, I think this relates to my comment about definitions as well. This is a statement about how DITA differs from DocBook, not really about the purpose of the TC itself.

 

In the Scope section, the list item that says “are optimized for navigation and search” is this still true? If we want to talk to optimized for search, maybe we should mention the subject scheme and talk to the rich taxonomy that adds intelligence to the topics, enabling smart query and retrieval via for example bots? Agreed. We do not mention metadata or subject scheme at all and topics are not inherently optimized without these items, so the bullet seems to overpromise without some kind of clarifying statement.

This section also talks about “reuse of community contributions”. We had some in the early days of the TC, but I don’t think we have any at this time. Is this statement still valid? I don’t interpret that this sentence has anything to do with the TC doing this, but again speaks to the value of DITA. Again, related to my comment about definition.

 

In the section “The tasks of the TC include”:

Towards the end of list item 5, we have this sentence: “The TC anticipates maintaining a set of core information types of general utility, implemented in schema languages (such as DTD or XML Schema) selected by the TC.” Why do we mention that specific schema technologies we support here? I think we should remove the content in the parentheses. The standard itself talks to the use of Relax NG as the normative schema and standard, so I don’t think we need this here. Plus, we no longer support XML Schema. Agreed. Although the language is “such as,” the fact that we don’t support XML Schema makes it misleading. At the very least the example should be RNG and DTD, but I support removing the parenthetical remark. Note that this should also come out of the second bullet in the List of Deliverables as well.

I don’t think we’ve ever done anything that’s mentioned in this list item:  Does the plugin registry (https://github.com/dita-ot/registrycount) toward the public registry of this item? Or is it not actually TC work since it’s related to the OT? Doesn’t the Adoption TC answer to the TC and therefore fulfill the aspect of “suggesting guidelines…” I’m not sure I agree that we haven’t done these things or even if we haven’t that they shouldn’t be part of the charter.

 

  • To design a generic methodology for specialized extensions of the base specification by user communities. This methodology may address issues such as delivery of a reference implementation, operation of a public registry for specializations, suggested guidelines for development of a user community's information types, and so forth. When the above tasks are completed, the TC may reconsider further work, which will be defined as allowed by the OASIS TC Process.

Should we delete this item? I don’t think it’s relevant to the TC based on what we do today.

 

In section “Anticipated Audience”, there is an apostrophe missing in the first list item: s/DITAs/DITA’s/

 

 

Looking forward to our deeper discussions on this.

 

Cheers,

Gershon

 

 

 

 

Gershon Joseph | Senior Information Architect | Precision Content 
Direct: +972 (54) 658-3887| Email: 
gershon@precisioncontent.com | www.precisioncontent.com

 

A picture containing drawing, food, plate
              Description automatically generated

 

Unlock the Knowledge in Your Enterprise™


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. ©2021, Precision Content Authoring Solutions Inc, Toronto, Ontario, Canada

 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]