Meeting: Bluestream XDocs DITA CMS with Oxygen and FrameMaker
Nenad Furtula, of Bluestream, and Scott Prentice, of Leximation, presented a multi-tool demonstration of the XDocs authoring and publishing features.
Nenad demoed (remotely from Vancouver, Canada) the latest features of the XDocs CMS. In particular he showed the Author/SME review workflow using Oxygen Author and XDocs Explorer with the XDocs SME Review Module. He also demonstrated various options for publishing through the XDocs Explorer.
As an example of a collaborative workflow, Scott (presenting locally) checked out the same files from the XDocs CMS and made edits using FrameMaker and DITA-FMx. He then demonstrated automated publishing using FMx-Auto and FrameMaker to create a PDF from DITA files pulled from the XDocs CMS.
After the presentation, we had lengthy discussions of options for authoring and publishing DITA content .. a really fun meeting!
Meeting: Using SharePoint to Manage, Review and Publish DITA Content
Brian Meek, of DITA Exchange presented a compelling demo of using SharePoint with DITA Exchange to manage, review, and publish DITA content. Lots of questions and discussion followed the formal demo making this one of the longest meetings we've ever had. Thanks Brian!
Info from Brian:
If your company uses Microsoft SharePoint, and you work with DITA content, please make an effort to attend this session and learn about the current capabilities of DITA Exchange software.
The session will address the combination of SharePoint and DITA from two perspectives: For those in need of a complete DITA implementation (Authoring process, CCMS, Review & Approval workflows, Multichannel publishing, etc.); and for those looking to augment an existing DITA implementation by taking advantage of SharePoint for collaboration & workflows, data integration, search, Web publishing and automated document assembly through Microsoft Word Templates or an integrated instance of the DITA Open Toolkit.
We will demonstrate how SharePoint sites can be built using dynamically-rendered DITA content, and we’ll also look at using various XML authoring tools with SharePoint, including a Microsoft Word "Customization" designed to guide business users and SMEs in the creation and editing of valid DITA topics.
We’re looking forward to an interactive, “show & tell” discussion about how the DITA information architecture and XML publishing model adds value to SharePoint, and how SharePoint provides an effective platform upon which we’ve been able to build sophisticated CCMS capabilities publishing processes...
If you would like more info on using SharePoint and DITA Exchange please contact Brian @ DITA Exchange.
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!
Looking for DITA/Drupal Volunteer Opportunity
Would one of your DITA-based, structured projects benefit from being published along with related, unstructured content as an information mashup on a Drupal-based website? Do you have the time and energy to participate in such a project on a short-term basis?
Dick and I are interested in working on a volunteer basis (no cost to you) on such a content-rich solution. We would like to start the project by mid-August and complete it by the end of September.
To see what we mean by "DITA/Drupal mashup" see our model sites: www.XMLdocs.info (WordPress) and www.DITAinfo.info (Drupal). Some of our blogs on those sites explain our vision, and you can click through the structured and unstructured information (the information domain is DITA itself).
Benefits to you: (1) Opportunity to experiment on a project you judge to have future business value (2) Opportunity to take advantage of all we have learned so far on these kinds of projects.
Benefits to us: (1) Opportunity to expand our knowledge and skill in this area (2) Opportunity to better understand client requirements and preferences.
If you are interested in exploring the possibilities, please contact us at 408-832-4212 or avanraaphorst@gmail.com. This is a one-time offer to an organization with the right profile and the ability to act quickly.
-Anna van Raaphorst and Dick Johnson
A model DITA on Drupal web site
We have just published our DITAinformationcenter on a Drupal 7 web site. It contains information about DITA and the DITA Open Toolkit at the 1.2 standard level. Now that we have published it on Drupal, you can search the topics by metadata tags or text and you can also see how to combine formal structured documentation with informal blog posts on a single site and at a reasonable cost.
Dick and Anna
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.