http://www.mekon.com/ DITA, XML, Workflow, Content Management and Process Automation - Best Practices, Tips, and Strategy en 2009-12-24T14:39:40+00:00 2009-12-24T14:39:40+00:00 http://blogs.law.harvard.edu/tech/rss Expression Engine 60 http://www.mekon.com/index.php/pages/company/why-dita-topics-arent-good-enough/blog/blog/ Happy Holidays everyone! I was woken up today at 5:30am by a head full of XML. This doesn’t happen to me that often, but probably more than it happens most people... This blog presupposes a certain amount of knowledge of XML and somewhat of DITA, so if you don’t know what either are I suggest backtracking a bit.  If you know XML but not DITA you can check my Intro to DITA webinar for a crash course. I’ve been thinking about this for a while but a recent conversation at X-Pubs 2009 with a salesman from one of the major DITA-supporting Component Content Management Vendors really kicked me in the butt to write this.  We were discussing a competitor of his who has implemented a Mark Logic (i.e. XQuery-based XML native) base for their system.  This blog is not an endorsement of any given product, but a hurrah for a company (any company) that takes an approach we’ve been nagging them to take for a couple of years now.  The approach is one we have in fact even already implemented as bespoke developments on Mark Logic and open-source databases, but is poorly addressed by the vendor community. The response from the first CCMS vendor was (paraphrasing), “So what? With DITA surely you just manage at the topic level?” The answer is: so lots of stuff. Lots of Stuff My colleague Mark Poston did a webinar a few months ago through X-Pubs walking people through a case study (sorry about the audio quality, and the zooming that the screen-share software does. It’s a bit raspy, so I suggest speakers instead of headphones, and you have to listen carefully as the text has been squished somewhat) where two features in specific demonstrated a heavy reliance on XQuery.  For those of you who don’t know, XQuery is a technology that has just (finally!) started to make waves.  Those of us in the industry have been hearing about it since the standard started development circa 8 years ago, but fine tuning it for release, tool support and industry understanding mean its “time” is only just dawning.  Although of course I recommend you take the time to watch Mark’s whole session, only certain bits are directly illustrative of today’s rant.  If you check out the webinar from about 47:30 on, it shows a DITA document (although the fact it’s DITA is not relevant) with database integration where a 3rd party XML data service is being interwoven into a user-created file.  Neat stuff.  From about 51:45 the system shows how you can enter mark up strings of XML (across element boundaries) to define areas of text that require specialist Subject Matter Expert (SME) approval.  In this case, data that requires Copyright needs to go to a copyright editor for administration, management and release.  As far as I’m concerned, by far the coolest part of this whole shooting match is when the Copyright editor is shown their optimised view of the content.  This type of interface with XML is very possible, but with fully topic-based access management, it's not easy. Early in the webinar in the MS Word DITA integration and on the left hand side of the management console, we see a DITAmap (basically a ToC (table of contents) laying out the hierarchy of DITA topics).  In the Copyright area, we see a view of a document that is hierarchical, but has only two levels and has nothing to do with the ToC of the document in question.  It is organised by the company that the copyright editor needs to talk to, not the document's ordering, and shows: the status of each individual bit of Copyright-requiring information, with buttons to change it from approved, waiting, rejected, etc.. a preview of the text in question a “Context Zoom” where if the Copyright editor needs more context to understand the text they are looking at, they can “zoom out” level by level in the XML file Exactly the It is worth noting here that the whole point of using Quark XML Author was to avoid using the term “XML” at all. As far as users are concerned they are not editing XML they are simply marking up content from point A to point B. XML is the enabler to a much more powerful solution than Word or an ordinary component-based CMS, but is made to look simple for the user. The power lies under the hood, and that’s where XQuery is invaluable. When Reality Attacks So, we’re seeing here a real-world use case, which I can say from client experience is not unique to this customer or industry, where we are managing XML fragments that: are not at all bind-able by topics individually cannot be grouped and ‘hived off’ into topics in advance for planned reuse; by definition they can’t exist until authoring-time. For those in the know, and especially for the second example, this is seriously, seriously, difficult to pull off with a purely topic-based paradigm, and to an extent without our friend XQuery.  I don’t want to make this blog all about XQuery, but the relevance of what you’re seeing here is that it essentially requires that you treat your whole DITAmap, if not your whole content set of many DITAmaps and Topics, as a single, query-able XML file: Each part of each document is accessible at any time for recombination, management and on-the-fly preview. Simple to say, hard to grasp just how useful it is. When Are Topic-based Systems Good Enough? As you may know Mekon work with many CCMS vendors and Technical Communications teams, and will sing the praises of our favourites when they are being applied in the right context.  Most, however, are optimised to manage the internal operations of a Technical Communications team, and hold on to the Topic / Data Module or a MRU (Minimum Reusable Unit) concept.  When either on the collaboration side (as in the copyright example), or in the delivery side, you want to get more fancy with your XML, they rely on downstream systems. Which in a way is fine, but being able to manipulate your content into new deliverables is part of the creation process, and therefore I’d say should be addressed in the CCMS creation-management layer.  In the case study I referenced, Topic-management and reuse were not major drivers, it was collaboration and delivery that were key, so we developed this system on top of a native XQuery Engine and XML repository (Mark Logic) because Topics alone weren’t good enough to get the job done. Anything that bound us completely into a topic-based management paradigm on the back end  without the ability to: easily and quickly display fragments as discrete manageable objects to the user combine content that doesn’t exist in topics (e.g. data feeds) seamlessly cheaply and quickly generate custom interfaces for viewing and managing these new “fragments objects” meant to deliver the end-to-end user experience we needed (to authors, managers and SME editors) would have been difficult, and an inefficient use of our resources.  Poor use of our resources of course also means poor value for the client – so, we didn’t do it. Horses for Courses Your horse might be a native XQuery supporting CCMS, or one that integrates tightly with a native XML-based system, if you want full management capability – status, validation, workflow – on things that aren’t discrete topics in the system.  If you are starting to think about how you can make your content experience more engaging than big flat PDFs and want to do things like this: Allow user compilation of their desired content, directly, regardless of whether you as a content provider decided that that was a “Topic” or not – theoretically, even if you didn’t think to apply any special metadata to it. Maybe tie this into a content licensing/purchases system if it’s IP with a £$€ value attached? Allow internal collaborative users direct and flexible access to only parts of the content, e.g.: warnings statements in proposals or specifications that legal or R&D might need to review/query anything: maybe you just want a user to be able to add custom metadata to any given element anywhere at any time! Dynamic extraction of compiled content (Automatically generated topics?) based on semantics found in other documents: E.g., you have lots of documents that talk about tools and prerequisites for doing certain tasks, and you want to generate a dynamic list of all the tools or prerequisites across multiple topics. (For those going, “Just use XSLT” yes, there’s definite potential there, but it is not as dynamic as you’ve got to write the XSLT in advance, n’est-ce pa? Arguments invited.) The Counter-Argument Did you notice that I mentioned the system in the case study was built on DITA?  That means that in fact the whole system is, technically, topic-based.  So, it is important that I clarify: it is not topics themselves that are the problem, but lazy CMS developers who look to topics as a way out of providing more flexible content management paradigms to their users.  I think it’s an extension of the difficulty in breaking the document mind-set.  They think that although you’re component content managing, but the desired output, all interdepartmental collaboration, and all user manipulation of the content are always going to be on whole topic chunks, or worse, flattened, rendered documents. The most common argument is ‘not enough customers are demanding that’, which means a huge lot in a software company (I worked in them for ½ my career, I know).   But, try a similar argument: “Our horse-drawn carriage customers don’t ask for carriages that can do 70kmph for 3 hours at a stretch without a break.”  If that made any sense we’d have no cars.  People don’t ask for what they can’t envisage, but that doesn’t they don’t need it, or buy when you show it to them. The line between publishing and creation is blurring as WIKIs, Web 2.0 and Intelligent Enterprise Content sweep over us in waves.  We need to be able to preserve our semantics right up to the user so that we can remix, annotate, and user-categorise it to our heart’s content.  Even if you’re in Medical, Military or Pharma, your users are still allowed to make favourites, search by categories or give paragraph specific-comments that you need to deal with on a sub-topic basis.  If you get 800 comments on different paragraphs across 1000 topics in a map, do you really want to deal with each of those individually by opening up each topic, or would you like the comment and it’s paragraph displayed in a summary view for you to step through... you decide.  This is where XQuery provides capabilities that other CCMSs cannot (so readily) support. When Topic-based Management is A-OK Tech Pubs applications that try to increment up one step from your existing document processes can get bye fine with topics.  There’s so much we’ve just grown accustomed to living with, that vendors don’t need to fix the things buyers don’t realise are broken.  Review tools in most CCMS are poor to non-existent, and still vendors get away with not implementing better ones because the functions they provide are still so much better than the doldrums of unstructured, copy-paste-based processes. You have multiple doc types (like install manual, admin manual and box top labelling) and across 4 products (3 types x 4 products = 12 instances) there are lots of shared pre-definable components.  Conref is a sub-topic reuse mechanism that can help you handle all your internal workings quite well.   Sometimes you may want to start here, and then evolve your use of semantics and XML up over time. Such approaches are supported by the DITA folks with the DITA Maturity Model and this is completely valid.  I for one still think the platforms should at least offer the under-the-hood architecture - and by implication, the flexibility in the front-end UI - that will allow you integrate easily into CM regardless of your background, and to grow as an organisation without necessarily outgrowing your CCMS in the first 3-5 years.  Thinking ‘we just manage topics’ is a lazy design attitude and cheats the customers out of features that could really save them time and frustration. 2009-12-24T14:39:40+00:00 http://www.mekon.com/index.php/pages/company/why-dita-topics-arent-good-enough/#When:14:39:40Z http://www.mekon.com/index.php/pages/company/knocking-down-babel-ste-and-reuse/blog/blog/ I've been working a lot with a long time client, Elekta Ltd, recently on a large scale Component Content Management project.  Elekta is in the Medical Devices industry and takes quality and content quite seriously. High on the agenda has been: Terminology and language consistency Reuse The problem What has been very interesting is how much more we are discussing the interrelation between these two than usual when I'm working on a CCMS / XML / DITA implementation. Most CMS project teams talk extensively about reuse, but few delve into the (pre)work that's really required to make your content reuseable before you actually get any software installed. Elekta is a small-to-medium sized company but it's been a pleasure to see how much they think in a Fortune 500 way.  Early on it was identified: If we're going to modularise all our content and reuse across teams, documents, and deliverables, then writing in a consistent way and furthermore, getting solid control of our terminology is going to be a big factor! Seems obvious, but so few organisations take terminology harmonisation into account in their global information management strategy. That is, if you reuse a topic that uses terms like 'Lever' and 'Knob' into a document with other topics that use equivalents like 'Handle' and 'Dial' then you're going to have readability and quality issues.  Then what happens when these inconsistent topics hit the poor translator/translation memory?  The problem will get worse as they try to find equivalents to the equivalents in dozens of other languages. It's like a broken telephone, the more steps you have in between your user and a single source of truth, the more chance your message will get distorted along the way. Distortion of the truth has the usual negative impacts we always talk about like brand equity damage, customer experience damage, increased support calls, slower machine fix time, etc. etc.. For example I recently presented a webinar where I told a personal story where I myself was lead astray by poor terminology management.  In a single interface screen, a piece of Online Presentation software used both 'Speaker' and 'Presenter' to mean, 'the one who presents.  I of course assumed that two different words used in the UI side-by-side would mean two different things, so I understood 'Presenter' as intended, but thought that 'Speaker' was referring to my computer audio speaker configuration settings.  As a result, I managed to switch the software from 'multiple Speakers' (which I took to mean stereo or multi-channel sound) to 'one speaker' (i.e., mono).  As a result, I locked all the other presenters out of the audio stream! Not nice... Fixing it Reuse vs. STE, Simplified English, and other Terminology Tools  Long before we started the CMS project, Elekta decided to get this terminology and language thing sussed.  Elekta was again quite forward thinking as unfortunately Simplified English and Simplified English Tools are little known outside Aerospace and Defence and Government circles.  So they have adopted an internal flavour of Simplified Technical English (SE, or STE,  training available from guess who) and started checking their source language not just against foreign language translation memories, but against itself and a term-bank of approved single-definition non-ambiguous terminology. That way they not only save costs (STE texts are some 20-30% shorter than the originals on average), but make sure that the content is: easier to read and use in the source language easily translatable and to a higher level of quality easily reused without creating inconsistencies in language and term use in the new reuse context And the tower of misunderstanding comes tumbling down! Here's one consultant seeing we're going to see good expansion of Simplified English (or Simplified German, Spanish or whatever, there's dictionaries out there already for loads of languages) outside of Gov and A&D as DITA and reuse continue their epic increase in popularity. 2009-07-27T13:02:41+00:00 http://www.mekon.com/index.php/pages/company/knocking-down-babel-ste-and-reuse/#When:13:02:41Z http://www.mekon.com/index.php/pages/company/xmetal_developer_dita_training/blog/blog/ Don’t ask me why, but it’s been a while since I’ve ended up delivering a really advanced XMetaL course, much less for DITA.  I guess because DITA is still in fact quite “cutting edge”. In prep for giving an online XMetaL Developer course, I got inspired to share some ‘Little Known Tips and Tricks’ for XMetaL... have a look. Training was interesting for me because for those who’ve been working with DITA for so many years now, inside what feels like the most active and thriving community this industry has ever seen, you can completely lose sight of the fact that specifically because DITA is so flexible and supported by so many tools, we’re getting more users than ever, and every day new people are showing up to the party.   When I did my Intro to DITA webinar last month, we got triple the registrations we were expecting!  Obviously, there are lots of new people out there still who still need the initial light shedding on the Ol’ Darwin Information Typing Architecture…! Also not par for the course, it was XMetaL Developer training.  It was for a client that we worked with last year.  They’re an independent and out-of-the-box group who always challenges me with interesting ideas and questions about the technologies they’re using, with so it's great to be teaching them to take their solution to the next level. Anyway - the rest of this is a bit ‘techie’ so, if that’s not your scene, be warned. “In-Parent” Configurations Anyone who knows XMetaL Configurations can tell you it’s great in terms of all the different ways you can represent or control interaction with an element (inline database forms, custom COM controls, toggling elements, mini-templates and so forth), but did you know that you can make these context-specific? In the CTM file editor in Developer, right-click on any element and select “In-Parent element” and then the name of your element (I find this UI a bit messed up, but that’s how it works).  You will get asked what element context you’d like and when you choose, you get a new line with your element on the left, and in the second ‘Parent’ column, you get the element you chose.  Now any changes to that new line will only affect the first element when it is a child of the second!  Imagine if for example <phonenumber> tags generally could be free text, but in the context of table cells, they would be controlled by a database-linked forms... dates, emails,  links or anything else you wanted to control could be controlled similarly. Drag and Drop and Copy/Paste Debugging Did you know – you can debug any piece of code in XMetaL simply by copying it to the clipboard and pasting it into a document?  Even things that check the user's active selection or interact with external applications still work.  All you need to do is have the proper string at the beginning of what’s on the clipboard (dragging and dropping onto the doc works too).  I found it an extremely fast and useful way to play with code without needing to build a whole project or close/open XMetaL. Like so: For JScript it's:      // XMetaL Script Language JScript: For VBScript:       ' XMetaL Script Language VBScript: e.g.:       //XMetaL Script Language JScript:      Application.Alert("Hello World!" ); OR more usefully, check variables or properties:      // XMetaL Script Language Jscript:      Application.Alert(Application.Path);      Application.Alert(Selection.Text); DITA Language Reference Inside Author (5.1 and up) Did you notice that if you if you are using XMetaL Author (not sure if this is just in Enterprise Edition?), when you right-click on any DITA element you have a link to the OASIS DITA Language specification for that element.  Don’t know what a <ph> tag is? Just enter one, right click, and look it up! This kind of customised contextual help can also be applied for any DTD.  I personally like to see this hosted in the Resource Manager to allow you to see help and your document in one seamless view, the way that Microsoft have learned towards a dock-able help ‘bar’ that runs down one side of the application. If you found this interesting or have any questions, please do contact me or leave me a comment.  I'm always looking for something to blog about! 2009-04-02T15:44:37+00:00 http://www.mekon.com/index.php/pages/company/xmetal_developer_dita_training/#When:15:44:37Z http://www.mekon.com/index.php/pages/company/look_ma_-_dita_webinar_on_demand/blog/blog/ Hello all, Just last week I recorded my first "on-demand" webinar session. I did an "Introduction to DITA" that I hope is simple enough for anyone to follow.  I've been on loads, but this is the first time I've done a fully solo session that actually makes a reusable learning asset intended for free online streaming. X-Pubs is doing a 3-part Webinar series on DITA at the moment starting with my introductory session, then one by Michael Boses of Quark and the DITA BusDocs subcomittee, and then Mark Poston is doing a case study where we've actually implemented a completely non-Tech Docs DITA solution. (more on the others is on the front page of X-Pubs.com) In my session, I have a live demo in the middle (always risky!) with some real DITA content.   Unfortunately the recording ends a bit abruptly due to a technical issue and there was a glitch briefly in the middle but neither affect the quality of the content.  As always, you feedback and questions are invited. You can view the recording here: http://www.x-pubs.com/site/news/1613/     2009-03-11T13:50:13+00:00 http://www.mekon.com/index.php/pages/company/look_ma_-_dita_webinar_on_demand/#When:13:50:13Z http://www.mekon.com/index.php/pages/company/web_20_and_cms_on_demand_podcasts_available_now/blog/blog/ Hi everybody! After my keynote at Doctrain West 2008, I was invited by MyTechnologyLawyer.com and the very well received idratherbewriting.com/ to do some interview spots. Download the MP3s here: MyTechnologyLawyer.com http://www.idratherbewriting.com/  The MyTechnologyLawyer.com spot was with: Emma Hamer Scott Abel and Rahel Bailie   all also well respected minds in the Content Solutions space! 2008-05-12T21:44:19+00:00 http://www.mekon.com/index.php/pages/company/web_20_and_cms_on_demand_podcasts_available_now/#When:21:44:19Z http://www.mekon.com/index.php/pages/company/quark_dynamic_publishing_solution/blog/blog/ On Thursday last week Quark held a short but very interesting product launch seminar to give a few important clients and press a glimpse of Quark’s Dynamic Publishing Solution. Mekon were also very privileged to be invited. For those of us who have been involved with technical publications for several years, the concept of dynamic publishing is not new. Mekon for one has developed dynamic publishing solutions for many years using SGML, XML, or a SQL database combined with tools such as E3, XyEnterprise XPP, Antenna House XSL Formatter and Quadralay Web Works to name but a few. Such solutions lend themselves very well to technical publication workflows, where content can be re-used for multiple products and document types, feeding through to several output or delivery formats. In the past two years we have carried out many Content Strategy Audits at high tech and manufacturing companies. In all these companies the results of the audit showed the potential for re-use in marketing publications, and it is already well understood that marketing departments need to produce many different output formats. This is where the problem starts. Marketing have different design driven challenges than technical communications and hence use products like Adobe InDesign and QuarkXpress to produce the ever changing marketing communications information. They are not about to swap these traditional design tools for content driven tools such as Adobe FrameMaker, JustSystems XMetaL or PTC Arbortext Editor. So all this lead up is to prepare you for what I believe is a fantastic step forward for marketing departments and their need to integrate with the wider tech comms content-driven workflows. Simply put, what has been missing is an XML content interface to allow marketing department to continue using their favoured layout tools and reap the benefit of this current XML revolution. Quark Dynamic Publishing solution has the potential to be this missing link. Ray Schiavone, Quark CEO, delivered the brief which indicates the importance they place on this product. Interestingly the demonstration showed In.Vision Express Author producing valid XML content, managed in an open source CMS, automatically publishing the content through predefined QuarkXpress templates to produce PDF and HTML output. Their plan is to add other output types, in particular mobile devices. I also heard that they are working on DITA support which is clearly where the market is going these days Watch this space. 2008-03-16T23:30:23+00:00 http://www.mekon.com/index.php/pages/company/quark_dynamic_publishing_solution/#When:23:30:23Z