Re: [dita-fa-edboard] RE: DITA Technical Committee Submission

[Bruce Esrig <esrig-ia@esrig.com>]

Hi Zak,

In its purpose and ambition, this seems like a Content Architecture. The
content that you're offering to publish would be a valuable addition to
what is publicly available about how to use DITA.

If you want to make this content publicly visible from a wiki site that
your company controls and administers, then you could post an
announcement about it in one of the categories under DITA Today. Under
Resources, perhaps.

If you want to embed it in a wiki hosted by
http://dita.xml.org,
then you could create an entry for the SunGard Higher Education Content
Architecture in the Solutions area of the DITA Wiki. If you wish to
protect it there, you could mark each page as modifiable only by
Contributing users (and Editors and Administrators). We could define you
and any colleagues you designate as Contributing users so that you would
have full access privileges.

Just some options,

Bruce

At 09:47 AM 6/25/2007, Zak Binder wrote:

Hi Bruce,

After evaluating the DITA specification, my team determined that we did not need all the elements that DITA supplied. After a few meetings to analyze the specification and figure out what we could trim out to better fit our needs, I decided to put the decisions we made on our development WIKI. The DITA WIKI pages at SunGard Higher Education are designed to be a DITA authoring cookbook that will become more and more specialized to SunGard Higher Education standards as our development process evolves.

The first page under the "recipe" for a task that a writer on my team will access displays:

 


Since this outline, if expanded fully, would be difficult to use, I limited the outline to include only the elements that I felt would be commonly used.

If a writer on my team has a question about the Task topic, clicking the "task topic" link in the outline will display the following:

 

The first column on the page contains the name of the element that is being displayed and contains a hypertext link back to the DITA specification (in this case the link goes to - http://docs.oasis-open.org/dita/v1.0/langspec/task.html). I did this so that my team always remembers that we are working off of a public standard and there is a reason why the <shortdesc> must always contain the purpose or theme of a topic and nothing else.

The second column displays all child elements that belong to the selected parent.

The third column displays any attributes that can be associated with the parent.

The fourth column shows whether the child element is required or not. At SunGard Higher Education, we've decided to make <shortdesc> and <taskbody> required along with the title that is required by the DITA DTD. If we decide at some point that we will not be using the <titlealts> tag, I will simply edit the page and remove it from the outline.

The fifth column shows how many of those elements we are allowed to use. For example, if we were to decide that  a Task must contain at least three numbered steps, the <step> element child on the <steps> page would show 3 or more.

All of the information in the final column was originally copied directly from the DITA Specification. The benefit of using our WIKI to display this information is that with a few mouse clicks, I can add an example as part of the title element such as:

        When authoring a Task, the title must start with an action verb and must never use a gerund. For Example: Create an e-mail message
        When authoring a Concept, the title must begin with the words "What is." For Example: What is an e-mail message?

I expect that as we continue to develop our standards, these pages will include a lot more examples and perhaps more specific descriptions to allow my team to work more efficiently.

Each child element on a page is a link to a separate page where that child is displayed as a parent. For example, if I click on shortdesc, I'll see:

 
Since we decided that <codeph> was not a valid part of a short description in our on-line help system, I simply removed it from the page. If at some point we decide that <codeph> is necessary, I'll simply add it back in.

I hope this helps explain our process and the WIKI usage at SunGard Higher Education. I'll be sure to access the Solutions area and see how I can contribute to the DITA community.

If you have any questions at all, please do not hesitate to ask.

Thanks,

Zak


Zak Binder * Advisory Technical Writer * SunGard * Higher Education * 4 Country View Road, Malvern, PA  19355
Tel 610-578-7456 * Fax 610-578-6195 * zak.binder@sungardhe.com * www.sungardhe.com

CONFIDENTIALITY: This email (including any attachments) may contain confidential, proprietary and privileged information, and unauthorized disclosure or use is prohibited. If you received this email in error, please notify the sender and delete this email from your system. Thank you.


Bruce Esrig <esrig-ia@esrig.com>

06/25/2007 07:57 AM

To

"Zak Binder" <Zak.Binder@sungardhe.com>

cc

"Carol Geyer" <carol.geyer@oasis-open.org>, "DITA Editorial Board" <dita-fa-edboard@lists.xml.org>, "JoAnn Hackos" <joann.hackos@comtech-serv.com>

Subject

Re: [dita-fa-edboard] RE: DITA Technical Committee Submission




Hi Zak,

Thank you for your interest and enthusiasm! We're making revisions to http://dita.xml.org that would make it easier to accommodate the contributions that you are offering to make.

Do you have a description available of the structure guidelines for content at SunGard Higher Education? The DITA Learning Content Subcommittee has been considering various variations on Course -> Lesson -> Topic, with a number of possible specializations for topic.

Also, for the wiki that you are working on, what types of pages do you have, and what is the content of each type of page? One possibility would be a page for each element, with a definition of how that element is used in your content. A second, complementary set of pages might describe types of content and the elements that are typically used to represent that content.

The article that we are working on regarding <keyword> is being revised to address both these points of view: what elements to use and what purposes to use them for.

Within http://dita.xml.org, we are establishing a new area, tentatively called Solutions (http://dita.xml.org/wiki-solutions), to accept new content from contributors who have solutions to particular problems in using the DITA language. There is also an existing area for specializations. Please take a look at the Solutions and Specializations areas. Then we can figure out where you would be most comfortable making your contributions.

Best wishes,

Bruce Esrig
Information Architect
Editoral Board Member, http://dita.xml.org

At 02:26 PM 6/24/2007, JoAnn Hackos wrote:
Hi Zak,
I was very pleased to meet you and learn how you are implementing DITA at the workshop. I'm forwarding this message to Carol Geyer and the editorial board. We are working on introducing a wiki to the dita.xml.org website. Your wiki for the DITA elements would be an excellent addition.

Would it be possible to have people add to the information about the DITA elements in the wiki? I'm thinking about a limited editorial group that can add information, clarify, etc. We get lots of questions about the DITA elements. In fact, our next showcase article discusses the elements associated with <keyword> so that might be an excellent start to produce a valuable tool.

JoAnn


JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver CO 80215
303-232-7586
joann.hackos@comtech-serv.com<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />

---

From: Zak Binder [mailto:Zak.Binder@sungardhe.com]
Sent: Tuesday, June 19, 2007 11:01 AM
To: JoAnn Hackos
Subject: DITA Technical Committee Submission


JoAnn,

When I returned to the office after the DITA Bootcamp, I immediately put all that I learned to the test. I gave a presentation to my team on my new DITA knowledge and I've started to refine the list of DITA tags that my team will use. I have started to modify the WIKI pages I created to reflect the DITA element hierarchy for SunGard Higher Education, and I wanted to let you know that I am interested in submitting this methodology to the OASIS DITA Technical Committee and helping in any way that I can.

Please let me know if this is something that the Technical Committee would be interested in, and if so, how I should proceed.

Thank you again for a great week of training. I'll be sure to keep you up to date with our DITA success stories as the project progresses.

Zak Binder


Zak Binder * Advisory Technical Writer * SunGard * Higher Education * 4 Country View Road, Malvern, PA  19355
Tel 610-578-7456 * Fax 610-578-6195 * zak.binder@sungardhe.com * www.sungardhe.com

CONFIDENTIALITY: This email (including any attachments) may contain confidential, proprietary and privileged information, and unauthorized disclosure or use is prohibited. If you received this email in error, please notify the sender and delete this email from your system. Thank you.