OASIS Darwin Information Typing Architecture (DITA) TC

Expand all | Collapse all

FYI: One Successful Experience Teaching DITA at the College Level

  • 1.  FYI: One Successful Experience Teaching DITA at the College Level

    Posted 01-06-2009 03:45



  • 2.  Re: [dita] FYI: One Successful Experience Teaching DITA at theCollege Level

    Posted 01-06-2009 04:20
    On 1/5/09 9:44 PM, "stan@modularwriting.com" 


  • 3.  RE: [dita-help] FYI: One Successful Experience Teaching DITA at the College Level

    Posted 01-06-2009 09:11
    
    
    
    
    
    
    
    
    
    
    

    Thanks for the very interesting and thought-provoking reflection, Stan!

    I had very similar experiences in teaching a similar post-graduate course at Swinburne University of Technology. I shared your finding that just when the students were becoming productive with DITA, the semester was over! I was interested to see that you also found your students to be a pleasure to teach. I think the subject matter is appealing in a number of ways. One of my discoveries (admittedly after just two intakes, with statistically invalid numbers!) was that the folk who excelled were the ones most scared of “technology”. The consensus to date is that DITA’s appeal to an experienced writer is a combination of it being methodology, and the separation of the “codey” presentation layer from the semantic mark-up layer. Semantic mark-up appeals to the writer in the student, while presentational mark-up (and the vagaries of page layout tools) does not.

    The main issue at this stage is that students leave the course and most go back to the workplace and continue using Word! We need more DITA adoption!

    Regards

    Tony Self

    From: stan@modularwriting.com [mailto:stan@modularwriting.com]
    Sent: Tuesday, 6 January 2009 2:44 PM
    To: dita@lists.oasis-open.org
    Cc: dita-help@lists.oasis-open.org
    Subject: [dita-help] FYI: One Successful Experience Teaching DITA at the College Level

    Hi all --

     

    I just completed teaching an undergraduate course on modular information development and DITA at Bentley University (Waltham MA USA). The course had its bumps, but succeeded in its goals all in all. I thought that you might find the student writing and my summary evaluation of the course (see below) interesting ... I have attached the DITA 1.2 PDF2 distillation. DITA may be more ready to break into academia and the undergraduate curriculum than we imagine.

     

    Stan Doherty

     



  • 4.  Re: [dita] FYI: One Successful Experience Teaching DITA at the College Level

    Posted 01-07-2009 22:55
    Hi Stan,

    Thanks a lot for your description and eval of your course.  I had thought that there was one DITA book that was good enough to serve as a textbook, though I can't name it.

    It  would be interesting  to hear directly from your students about why they took the course and what about it they got the most out of.

    Looking forward to working with you again in re-activating the Boston DITA UG.

    Regards,

    Nancy



    On Mon, Jan 5, 2009 at 10:44 PM, <stan@modularwriting.com> wrote:
    Hi all --
     
    I just completed teaching an undergraduate course on modular information development and DITA at Bentley University (Waltham MA USA). The course had its bumps, but succeeded in its goals all in all. I thought that you might find the student writing and my summary evaluation of the course (see below) interesting ... I have attached the DITA 1.2 PDF2 distillation. DITA may be more ready to break into academia and the undergraduate curriculum than we imagine.
     
    Stan Doherty
     

    Course Evaluation

    This topic offers a few summary comments, evaluations, and suggestions.

    There isn't much literature about teaching modular information theory or DITA in the undergraduate curriculum. Until there is a forum to collect and share information, these informal evaluations will have to suffice.

    Course highlight ....

    No question ... the best part of teaching this course was the opportunity to work with such a fine group of students. The path of least resistance for many students is to learn conventional wisdoms in conventional ways from conventional instructors. This group of young professionals stuck with a course that focused on new wisdoms, new methods, and unconventional methods of instruction. I wish that I could hire all of them.

    Course lowlight ....

    We ran out of time just when the class was becoming confident with DITA and what they had learned. I can't conclude that the material requires or warrants more than one semester, but it is pretty clear that the big payoff happens shortly after the semester winds down. Wow, if we only had a few more weeks together ....

    What worked well ...

    Most elements in the class plan worked well.


    • DITA concepts: As a coherent body of knowledge, DITA works. We spent quality time with the DITA 1.1 Architecture Specification; the students found some of it over their heads, of course, but they understand the basics and were able to employ key DITA concepts and methods when developing their final projects. DITA is not beyond the reach of college undergraduates; it is entirely appropriate to move it more formally into the curriculum.
    • DITA Open Toolkit: The DITA-OT was developed by senior technical communication professionals for senior technical communications professionals -- not by or for 20-year-old entry-level professionals. The class found the DITA-OT environment -- Java, environment variables, command shells, ant scripts, etc. -- quite foreign at first, but they studied it diligently and became proficient at it. They routinely generated XHTML, tocjsbis, WordRTF, and PDF output from source topics that they authored and managed. I would love to see some simplified, captive version of the Open Toolkit optimized for undergrads, but short of that it is important to recognize that working with the Open Toolkit was beyond no student in the class.
    • MS Word linear-to-modular deconsruction: Using a tool that was familiar to the students -- MS Word -- worked well in the section of the course focusing on deconstructing linear manuals. The same tool that the students used to build linear docs (term papers, reports) served them equally well when deconstructing those same linear docs. Contrary to popular opinion, most of the basic principles of modular information development are independent of XML or DITA.
    • Course-specific sample DITA domains: Working in class with a tightly focsued set of DITA source files proved to be more valuable than lectures, slides, or demos. I spent a lot of time developing those sample domains; they were well worth the investment.
    • Visitors: Toward the end of the class, we were privileged to have Boston-area practitioners of modular writing and DITA join us in class and in local restaurants. When the students heard our visitors espouse many of the same points that I had been teaching them for many weeks, that tended to bolster the overall credibilty of the course. It was especially important for them to hear that these successful writers and architects were equally competent with linear and modular information development -- and could articulate the relative strengths and weaknesses of each architecture dispassionately. There's a significant market for entry-level professionals in converting legacy linear docs to DITA; hearing from hiring managers that becoming proficient in that area opens career opportunities.

    What needed improvement ...

    No first-time course offering is perfect, so there were several notable goofs and failures (mostly on my part in structuring the course).


    • Textbook: I used slide shows from conferences, specs, and little excerpts from the top 10 books on modular writing. Some of it worked, but there is simply no substitute for a well-written, coherent textbook. I do not recommend attempting to teach this class without one in the future.
    • Student laptop configuration management: Bentley University has been a pioneer in the area of academic computing since the mid-80s. Every full-time Bentley student receives a decent Windows laptop (IBM or HP). Part-time evening students bring to class whatever they can afford or borrow. We did not have the luxury of running the DITA Open Toolkit on a robust, consistent PC configuration. Bad memory, bad drives, bad CD-ROM drives, dead USB ports, and 95% full disk drives made installing and configuring the Open Toolkit a weekly challenge. The folks running Linux and MacOS seemed to fare better that the Windows folks. We muddled through, but it was a constant distraction.
    • Basic sample DITA domains: There are no free, available collections of robust DITA sample files. The DITA architecture spec comes closest, but that actually demonstrates relatively few non-obvious DITA features. Other available collections of DITA topics no longer build in the Open Toolkit, so they are functionally irrelevant. We need robust sample files.
    • Eval copies of multiple DITA editors: When structuring the course, I was not sure how well students would fare with native XML editors. If I asked them to purchase an editor and they hated it, the entire course could go "pear-shaped" quickly. I decided to be conservative and to ask student to use two 30-day eval editors, XMetaL 5.1 and Oxygen 10. At first they appreciated not having to buy yet another piece of software, but eventually many of them purchased Oxygen and considered it a part of their software toolkit. Although it was neat to show them how the same XML DITA topic, whether opened in XMetaL or Oxygen, used the same DTDs, elements, and attributes, it would have been better to get into one editor early on and then learn it more thoroughly.
    • The "Why We Need DITA" pitch: I was so accustomed to visiting companies in the Boston area to make my "Why we need DITA" pitch, I assumed that it was as relevant to students as to writing professionals. Wrong. The key motivators for modular information and DITA -- reuse, consistency, translation costs, overhead -- are simply foreign and irrelevant to the academic community. Students have never experienced the downside of linear informatin development, so they have no frame of reference for understanding -- at least initially -- why XML and DITA are a big deal. I was pitching them a solution to problems that lived outside their realm of experience.
    • Topic elements: I was too cavalier in teaching basic topic elements. I gave them a couple of model topics and some lists of common topic elements, but did not spend much time reviewing the most common elements and grouops of elements. My bad.

    What to do differently next time ...

    I am not currently scheduled to teach this course again ... bu I would love to take another swing at it . Here's what I'd do differently next time.


    • Textbook: There have to be 100 available textbooks on college writing in the linear architecture ... and a total of 0 (to my knowledge) addressing the modular achitecture. I know what needs to be in such a textbook and have started writing it in DITA (of course). Hopefully some of the IDCC390 students would be willing to review it as I draft sections.
    • One complete and robust sample DITA domain: I developed several separate little DITA domains for in-class labs on specific topics in DITA, e.g. topic types, mapping, filtering, conref libraries, metadata, etc.. I distributed these discrete domains because I was concerned about overwhelming the class with one, overloaded domain. This concern was unfounded. Students who might have been confused by a set of sample DITA source files that contained more features than pertained to their immediate asignment were not particularly adventurous about looking at files outside the immediate assignment. What they didn't see . . .. The more technically adept students would have benefited from seeing a more complex set of DITA files with all bells and whistles turned on (if you knew where to look). I will d efinitely consolidate all the little sample DITA domains into one, carefuly layered domain that we can unwrap week-by-week and layer-by-layer.
    • DITA editor: We need to start working with real XML modules in a real XML editor earlier in the course, perhaps as early as Week-3. If XMLMind Personal Edition supports DITA more completely, I'll go with that ($0). Otherwise Oxygen Academic Edition is quite affordable ($48).
    • DITA on a stick: Although we managed to install DITA-OT 1.5 M4 on Windows, Linux, and Mac laptops, we devoted more time to debugging each installation and configuration than I had imagined or planned. If the class were larger than 8-10 people, I would have been doing as much IT support as teaching. I propose bypassing installation altogether next time by running the JDK and DITA-OT off basic USB thumb drives (I would provide them). All that the students would need to do is to set environment variables on their laptops, classroom lab PCs, or dormitory PCs. Setting up a full DITA-OT production environment for the sake of authoring and building a small handful of topics at a time was overkill.
    • Collaborative writing: I wanted to do more with small groups and collaborative writing by the time we got into DITA ... but we ran out of time. I had the sense that the class was just hitting its stride with DITA and its "group" possibilities when we had to wind down the course.


    ---------------------------------------------------------------------
    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



    --
    _____________
    Nancy Harrison
    Information architect
    Globalization specialist  
    nancylph@gmail.com