Meeting: DITA and Drupal — the “Dynamic Duo”
Anna van Raaphorst and Dick Johnson (the Dynamic Duo!) presented an update to their work on developing "mash-up" websites using DITA and Drupal. We had a good turnout for both in-house and virtual attendees.
The presentation was a discussion and demonstration of three of our rich-text, model websites:
What motivated us to create the model websites?
We kept hearing this story over and over again from our clients. Does it sound familiar to you?
As the owner, manager, or creator of technical information, youíre constantly trying to figure out how best to achieve accurate, useful, and accessible information solutions of high business value to your clients and customers. You also worry a lot about how to take advantage of the best standards, tools, and publishing environments available, and how to do it all on a shrinking budget.
In particular, you want the information you produce to be of professional quality, accurate, and essential. You would like to offer it to your users in print, on the web, and on multiple popular devices.
Structured information written to the DITA or DocBook standard often demonstrates these characteristics. However, depending on the experience level of the professional staff, the published result may fall short in solving your users' day-to-day problems, and it may be expensive to produce.
Yes, you also want your information to be relevant, popular, and accessible. How could you attract some sharp subject matter experts (SMEs) willing to share their "in-the-trenches" knowledge as an altruistic endeavor? And wouldn't it be nice if they were also capable writers and more than willing to update the information over time?
Unstructured information can be all of these things, but it can also be poorly written, out-of-date, and unruly to manage.
Is it possible to achieve ALL of the objectives with NONE of the common problems?
We created our model websites with this goal in mind. We decided to call our solutions "information mashups," because they contain both structured and unstructured information that is collocated and is displayed to users as a content "collection."
After about a year into this project we believe that this kind of DITA/Drupal content solution offers exciting and compelling possibilities, and we are pleased to share our thoughts and also learn from your experiences.
What questions will be answered in the presentation?
- On which publishing platforms did we prototype our solutions, and how did they compare?
- How did we develop our Drupal sites into mature models?
- What are the key DITA and Drupal 7 features that we believe have contributed the most to our information solutions?
- How could you make use of our models and lessons learned to build your own publishing solutions using DITA and Drupal?
Meeting: Canceled
Meeting: FrameMaker, RoboHelp, and DITA
Tom Aldous from Adobe provided a great overview of what's available in the Technical Communication Suite, and in particular the DITA features in FrameMaker and RoboHelp.
For details, visit www.adobe.com.
Thanks Tom!
Meeting: Generating PDFs from DITA using DITA-FMx and FMx-Auto
Scott Prentice, president of Leximation, Inc., presented a demo of DITA to PDF publishing through FrameMaker and DITA-FMx. The new FMx-Auto addon for DITA-FMx, unlocks the API features in DITA-FMx to allow automated processing and publishing (in particular PDF publishing). With FMx-Auto installed, you can create your own scripts using the FDK (FrameMaker Developers Kit), FrameScript, or ExtendScript. Or, you can use the AutoFM plugin provided with FMx-Auto, which lets you open, process, and publish your DITA map into a PDF.
DITA-FMx supports FrameMaker versions 7.2, 8, 9, and 10, and FMx-Auto is available in server and desktop versions depending on your workflow and needs.
Even if you're not using FrameMaker for authoring, you can take advantage of its superior and easy to use PDF publishing capabilities.
Meeting: Codex – “the easy DITA editor for everyone”
Adam Kozyniak, Co-founder and CEO of Codex Systems presented their new "light weight" DITA editor called Codex. This editor is targeted at people who may be able to benefit from the modular nature of DITA authoring but don't need (or want) all of the overhead imposed by an editor that supports the entire DITA specification. Codex is an Adobe AIR application, which means that it will install on both Windows and Mac systems.
At this time Codex only supports the creation and editing of "topic" topics and a limited number of elements. The interface is very easy to use, and could be used by anyone regardless of their knowledge of DITA or structured authoring. Codex also lets you create maps, and has a very slick method for adding and arranging topic references. For this feature alone, I'd consider using Codex as an easy way to create new maps.
After the presentation we had a lengthy discussion of the pros and cons of such an editor, with many people feeling that a lightweight editor definitely has its place in their organization, but it would need to be a bit more feature-rich than Codex is currently. Because of the limited support for elements and topic types, it may be difficult to integrate into many existing authoring workflows. We discussed a possible feature that would allow the end user to define the set of limited topic types and elements, and thought that this could resolve the issue of wanting to "keep it simple" while remaining flexible enough for various needs.
It sounds like Codex will be adding more features over the coming months, so this is definitely something to keep your eye on.
» "Video" recording 1h11m [49.5 MB] - Unfortunately the video seems to be messed up! The audio is good though. To actually see Codex, go to their website and download a trial.
This meeting was quite the event. Adam was presenting remotely from Japan, we also had remote attendees from Israel, Florida, and Los Angeles (well, actually Orange Co.). Our in-house audience was made up of many of the usual folks from the area, but we also had a couple of out of town guests from North Carolina and Los Angeles. It's great to be able to include so many people in our gatherings! Thanks again to Citrix for the use of GoToMeeting which makes it possible to include remote attendees!
Meeting: What’s new in Arbortext 6.0
Liz Fraley of Single-Sourcing Solutions presented slides and a live demo of PTC Arbortext 6.0. This new version of Arbortext offers full support for DITA 1.2. It also adds Schematron support, additional languages for spell checking, and other enhancements.
Slides to be available soon.
2011-06-08_SVDIG-June.mp3 - audio
Meeting: DITA Classification and Subject Scheme–Picking up where metadata leaves off
Joe Gelb of Suite Solutions, presented to a large crowd of in-room and virtual attendees, a discussion on the DITA 1.2 Classification and Subject Scheme.
Metadata is used by many to categorize DITA content. But categorization is not enough. More and more, companies are developing taxonomies to enable easier access to information. As you consider dynamic publishing and web deployment to meet the evolving expectations of your content consumers and the Google generation, classifying the subject matter in your content set and the relationships between that subject matter becomes critical. Using a real use case, Joe will demonstrate how you can use the DITA 1.2 classification and subject scheme to create, apply and publish your taxonomy using the same architecture you use to develop, manage and publish your DITA content.
Video recording 1h15m [67.8 MB] - I apologize for the extra noise near the end as I was moving the Polycom around to try to pick up the questions from the audience.
Meeting: Dell’s use of Trisoft and Arbortext
MaryLee Grant and Laura Clymer from Dell gave us a great overview and tour of their DITA authoring and publishing workflow using SDL Trisoft and PTC Arbortext.
More info to come soon!
Meeting: Canceled
Meeting: DITA/Web Mashups
Anna van Raaphorst and Dick Johnson lead a very interesting discussion about techniques for leveraging DITA content on websites. Dick has created a Python script that "publishes" DITA content into two different web CMS systems, WordPress and Drupal. This content is treated as the "reference" material, and once published it appears as integrated content on the website. They have two different websites that make use of this technology ..
- www.xmldocs.info (WordPress)
- www.ditainfo.info (Drupal)
Handout: DITAmashups_20110209.pdf
Scott Prentice mentioned that he had implemented a method for exporting DITA content from a WordPress website. This was used to create a book honoring a retiring professor. Past students were informed about the website and they contributed comments to the WordPress blog. Scott was then able to export all of the comments (including pictures and formatting) to a single DITA file that was opened in FrameMaker, where it was then exported to PDF. The PDF was sent to lulu.com to create a small hardbound book as a present for the professor.
Meeting: Round table discussion – importing DITA into InDesign
We had an interesting discussion dealing with how to best import DITA files into InDesign (specifically CS4 and CS5). It was a very hands-on meeting, with a real-world project as the test bed.
Like most DITA-type projects the important thing is the preparation. Importing the actual DITA files is as simple as File > Import XML, and then dragging and dropping elements onto the artboard.
Create Paragraph tags to match your DITA tags and use Structure's Map Tags to Styles to create a table that brings in the formatting easily. To modify the text, just edit the paragraph style.
When adding multiple DITA files, use Append when adding to an existing flow (good for columnar text) and use Merge when creating a new flow (good for individual text boxes).
Notes provided by Joanne Grey
Start Thinking Like a CCO (Notes)
The November meeting of SVDIG was held Wednesday November 10 at 7:00pm at Dell KACE, 1981 Landings Drive, Mountain View, CA. Presenting were Cynthia Canino and Tim Bombosch of Astoria Software (a Windows-based, object-oriented content repository). Approximately 25 people attended.
The talk was very interactive, with many audience members asking questions and participating in the discussion, especially to debate the appropriate metrics of the ROI calculator.
Cynthia and Tim began by stating that the title of "Chief Content Officer (CCO)" is a common title in the broadcast industry (in which "content" has high acknowledged value) but is rare in high technology. They suggested that content should (or DOES) have higher value in the technological realm, and that exploring and surfacing the value is in the best interest of both users and content producers.
According to Cynthia and Tim, some of the important values that drive CCOs are efficiency, branding, quality, compliance, and revenue.
The last part of the meeting consisted of a run-through of a spreadsheet set up to calculate ROI resulting from a typical move from unstructured (and unmanaged) content to structured (and well managed).
-Anna van Raaphorst
Meeting: Start Thinking Like a CCO (Chief Content Officer): Understanding the Corporate Value of Content Management
Cynthia Canino and Tim Bombosch of Astoria Software presented this thought provoking session on treating your content more like a corporate asset.
Meeting: Writing Effective Task Topics in DITA
Another great presentation by Michelle Carey and Shannon Rouiller (Technical Editors and Architects at IBM)! They covered the fundamentals of creating a DITA task topic as well as some of the more controversial and confusing issues that writers run into when creating tasks.
Notes from Tom Idleman (Thanks Tom!)
- Combine small tasks, such as “Click OK”, with more significant tasks in one step.
- Beware procedures that simply list imperative steps to interact with the UI without setting context or talking about why the user is performing the steps: “1. Click A. 2. Click B. 3. Click C…”
- 9 steps, maximum, per task topic.
- Only describe one way to do something.
- Tag optional steps with the attribute importance set to optional.
Note that IBM output generates an “Optional” label for steps tagged with importance = optional. (The label is not generated with a pre DITA-OT 1.5 PDF processor, a known issue with previous versions of the standard PDF processor.) - Instead of tagging something like “The blah window opens” as a <stepresult> of a step, use the information to set the context of the following step: “In the blah window, do thus and so.”
- Use <choices> when a user has several choices in a step that can be explained in a short phrase. Use <choicetable> when a user has a combination of options, such as “In Windows, do this. In Linux, do that.”
- IBM uses standard headings in task topics for the various parts of the task topic as follows:
- Before you begin (Prerequisite)
- About this task (Context)
- Procedure (Steps)
- Example (Example)
Or if a <title> element is used in thetag, the text Example is overridden by the text of the <title> - Results (Result)
- What to do next (Postrequisite)
- IBM uses inline icons: “Click the (graphic of icon) icon.”
- IBM uses gerunds to start task topic titles: “Medicating Your Cat”
- IBM tags command names with <cmdname> when talking about the command and <userinput> when the user has to type the command name at a command line.
- To construct a supertask, or in other words, a task that consists of many subtasks, IBM uses the following strategy in a DITA map:
- A concept topic <topicref> that points to a concept that talks about the overall supertask.
- An attribute setting of collection = sequence for the concept topic <topicref>
- Embedded <topicref>s that point to the tasks that make up the supertask within the concept topic <topicref>.
- The result is a concept topic with numbered links to the tasks that make up the supertask that looks like the following:
“Emergency Diving a Submarine
When your boat is spotted, submerging quickly is essential. The emergency-dive process is both complex and unforgiving. The individual tasks must be performed in the proper order and in a timely manner:- 1) Clearing the Bridge
The first step of an emergency dive is to get all personnel off the bridge of the submarine and safely into the boat. Typically, the OOD (Officer of the Deck) yells "Clear the Bridge" and sounds two bells to signify an imminent dive. - 2) Closing the Hatches
Before a submarine can dive, all external hatches need to be closed. Typically, only the conning tower hatch will be open, but more might be open depending on recent activity on the boat. - 3) Stopping the Engines
Submarine diesel engines require air intake to function. To prevent possible damage to the engines, stop them before closing the main induction.
…”
- 1) Clearing the Bridge
- To set prerequisite tasks, IBM sets the importance attribute to required for prerequisite tasks. This automatically creates a link in the prerequisite section of subsequent sibling task topics to the topic that’s topicref is set to importance = required.
Note that this doesn’t work for our standard output. It’s currently unknown whether our changes to the OOB OTK functionality is short circuiting this behavior or if IBM has added this to their output.
Free Resource: Fifth Edition of DITAinformationcenter (DITA 1.2, Toolkit 1.5.1)
Hi, All --
Dick Johnson and I have just released the fifth edition (publishing date June 30, 2010) of our DITAinformationcenter code distribution, documentation, and DITA project sample source files, available at:
www.vrcommunications.com/resources.htm
or
www.xmldocs.info
This release focuses on DITA 1.2 features and DITA Open Toolkit 1.5.1 (final build).
The code distribution contains:
- DITA Open Toolkit 1.5.1 (final build)
- PHP interpreter 5.1.4
- A number of PHP debugging and reporting tools (also available in prior editions)
- A new Python repair tool (DITArepair) that fixes bad references (for example, if files have been moved and links broken) and also serves as an example of how Python can be used effectively in the XML/DITA environment
The documentation contains several DITA 1.2 features:
- Extensions to conref, conaction pushreplace: A Python script run in a preprocessing step to put keywords into shortdescriptions, both keywords present in the topic itself and also those keywords "inherited" from container topics
- Keyref: The values for publisher, copyright, and vrm version now have a single definition in a resource topics (instead of being defined separately in each topic)
- Coderef element: We have replaced some of the inline code examples with coderef elements that point to items in a code directory
Information describing how we implemented the 1.2 features are described in one of the topics (published as an appendix in the PDF output target).
Other documentation features:
- Added a section on trends in global communication and why DITA helps to solve some of the current challenges
- Information about our recommended DITAworkflow methodology based on the agile software development process
- New localization and translation topics and core vocabulary items
Sample DITA projects:
- As before, our grocery shopping and garage samples (garage is an expension of the garage sample available with the Toolkit)
- The current DITAinformationcenter source files, possibly useful as a model project of moderate size (350 topics) and complexity, and for testing processing tools. It contains a wide variety of DITA features, both from 1.2 and prior standards.
As always, comments are welcome. We hope the resource is useful to members of the DITA community.
-Anna and Dick