We've successfully moved from unstructured to structured FrameMaker, creating an extensive EDD to cater for the different elements (type of content) our documents contain. This is working very well for us. Now we want to move to the next step - using DITA.
Just like starting out with Structured FM, I'm at a complete loss where to begin.I've watched a number of YT videos on the topic, but most seems to go with the assumption that you're already familiar with DITA. I need something that goes back to real basics.
Can anyone point me in the right direction?
DITA is designed for topic-based authoring, so I usually suggest that my clients get a book that describes the DITA DTD/schema so they can see if their documentation can be made to fit into the DITA structure. Or you can watch videos or take a course that describes DITA and its elements and attributes. If you determine that DITA is right for you, then it is a matter of customizing the FrameMaker DITA templates to match your desired look and feel.
"DITA is designed for topic-based authoring". How is this different from a FM Book made up of various documents, each being a separate topic of content?
DITA is a specific content model, with a specific list of elements and attributes.
An unstructured Fm book does not have an enforceable content model (You could, if you wanted, start a topic with a table. Not so in a structured document that did not permit this.)
You'll want to look into creating an XSLT that maps your current structure into DITA (frameexpert/Rick Quatro can help you with this, as can others)
@Matt S - Tech Comm ToolsSo DITA has predefined Elements that are to be used? Hmm. Not sure if that's going to work for us. Our structured FM documents already use a customised EDD.
The content in our training manuals are generic, so we're looking for the best way for our consultants to create customer-specific manuals, containing both existing content and customer-specific content. Unless there is a way we can customise the DITA templates to use our EDD.
So you want to keep your current content model, but want to customize the look of the output?
@Matt S - Tech Comm ToolsThe output is to remain the same as our current documentation.
To illustrate, we have a training manual on the Sales process. This manual currently contains the following structured FM documents:
The FM documents containing the processes, e.g. Creating a Quote, would consists of a number of sub-processes each with their respective step-by-step instructions, e.g.
However, these cover the generic product processes.
A consultant could have a client where one or more steps in one of the processes are different or not applicable. We're looking for an 'easy' way a consultant could take our standard training manual and tailor the content to the specific client, but still adhere to our structure rules (from the EDD) and output a document that still has the same look as our standard training manual.
TLDR; Tailored/customised content for a specific customer but with the same look for the output file.
Ok, so you use conditional text, text insets, variables, and cross-references to reuse content.
Given that you're in structured content, you'll need to add attributes to some elements to manage this.
A benefit to authoring with the DITA content model is that the structures you need are already in place.
*What got you thinking you needed to use DITA, if you need to keep your current content model?
@Matt S - Tech Comm ToolsI've never had much success using complex conditional text settings - they work great if only a single conditional text rule applies to the text, but when you start having conditional text settings that require multiple conditions in which context should/should not display, I've found they work unreliably and you end up with content showing/not showing incorrectly. Some of our content already contains conditional text settings as the content is used in multiple manuals as text insets. Adding client-specific conditional text adds a complexity I'd rather avoid.
After watching several YT vidoes on DITA, I was hoping it would work for us, but it doesn't look like it will.
That's the trouble with producing a content model from scratch...there's a lot to do, even if you don't change directions in the middle of the project. That's why you'll see so much discussion of DITA, S1000D, and aerospace/defense standards. When the content model is already created and supported (by Fm in this case) you can start with content and reuse more easily, even if the content model isn't 100% what you'd have wanted or chosen.
I was hoping the existing standards supported by FM would work for us as is, but doesn't look like it will.
I've already spent a fair amount of time creating an EDD for our collateral and a conversion table to convert our existing unstructured documents to structured FM. I'm happy to invest the time and effort into creating a 'standard', provided it works for us. We may end up with some sort of 'hybrid' module.
I agree with Matt.
The thing is, building your own (proprietary) XML architecture may sound tempting at first. You can create all the element names so nicely yourself, and they'll be called what paragraph formats used to be called.
I started the same way a long time ago. But it quickly gets out of hand, especially when there are many authors ("But I really, really need this additional element," "Nah, but this element must be allowed in this place too!").
After a few years, you have a colossal architecture with hundreds of elements, a huge DTD/EDD, lousy performance, authors who can't see through all the elements. Somehow it is still XML, but there is no real structure anymore. And there are more and more problems: updating stylesheets for authoring and output, dragging element definitions in the filters of translation tools, adapting more and more complex XSLTs, e.g., for SmartPaste, and so on.
At some point, no one can keep track anymore, and in the worst case, the original architect doesn't even work in the company anymore. Specialized developers are then brought in for a lot of money to clean up and simplify the whole thing so that the authors can work halfway productively again. And in the end, everyone ends up with DITA.
(That's about the 10-year curve I've seen in I don't know how many companies).
Over the last 10, 15 years, I've become more and more of an opponent of "custom XML" and more of a fan of standards, especially DITA. The advantage is that an international standard like DITA not only has broad tool support (starting from CCMS systems all the way into the translation supply chain), but it's easy to find authors who feel at home in it. There are enough specialists when particular requirements are needed.
The international OASIS committee maintains DITA. Following the detailed discussions in the committee about specific elements and attributes, it is easy to understand the intellectual effort that goes (and must go) into developing an XML architecture that can be used as widely as possible. I think it is less and less a good idea – from an economic as well as a technical point of view – to want to make this effort in one's own company for one's own architecture.
Yes, you may have to compromise on a standard architecture, and reduce the (usually only supposedly necessary) complexity, and break down the hundreds of individual rules to a few. But it is worth it!
Stefan has valid points here, but let me give a counter-point. If DITA (or any other "off-the-shelf" schema) doesn't fit your documentation needs, then you may have to change the way you structure your documentation to fit the DITA (or other) content model. This may not be appropriate for all document sets. It can also add complexity to the process of moving from unstructured to structured authoring. Instead of presenting authors with a long list of paragraph formats and a style guide, you may be presenting them with a long list of elements that they are not familiar with.
For some unstructured documentation sets, a custom schema that follows the general pattern of the current documentation may be a better solution. You can provide a simplified EDD that allows authors to ease into structured authoring, while enjoying the benefits of "guided authoring", context-sensitive formatting, and validation. When developing these types of projects, I use DITA-like element and attribute names where possible (p, ul, li, title, etc.) to facilitate later conversion to DITA (if desired).
I am surprised that Adobe doesn't promote its ability to create custom structured applications more. By promoting DITA, Adobe has actually facilitated some clients to move away from FrameMaker because of competing DITA tools and the use of the DITA Open Toolkit for output. They make the transition to structured authoring in FrameMaker via DITA, but then find that they don't need FrameMaker to do DITA. I have seen this with some of my clients.
As far as I know, FrameMaker is the only major tool that allows you to create custom structured applications via its excellent EDD model. Regardless of the schema, FrameMaker gives you true WSIWYG PDF output and you can get other formats via XSLT. DITA is good, widely used, and has good tool support. But a custom schema can be good for many types of documentation and can provide the benefits of structured authoring for its users.
This is what the
@audience attribute is for in DITA:
<p audience="enduser">Enjoy this training course. After going through it you will be a rock star.</p> <p audience="admin">This certified training course is for IT-Professionals only.</p>
You just apply your self-definied attribute values. For HTML5 output you define the values and then users of the output can "filter" the content on their own with checkboxes, or you create multiple outputs. As uch filtering is not there in PDF, for PDF you would just create multiple PDFs.
Personally, I prefer this way of attribute-based filtering over conditional text in XML projects.
Thank you everyone for your input on this question. Much appreciated.
Having looked at the the Elements available in just a DITA topic, none of our content writers/consultants won't have a clue what elements to use. They will find it endlessly frustrating and just end up creating documents in MS Word because it's easier. It also doesn't enforce the restrictions we have in our Corporate Style Guide, e.g. bulleted and numbered lists cannot be more than 3 levels deep; no more than 6 heading levels are allowed under a topic.
In contrast, our custom EDD has elements that our content writers/consultants can relate to, e.g. Heading, Paragraph, BulletList, NumberedList, Screenshot, InlineImage, Notes, FieldList, etc.
I can see the benefit of going with DITA if you don't have any sort of document structure in placed, or if you're in an industry where there is an established structure that you have to adhere to. Neither is the case in our organisation. We're also fortunate that our Style Guide for training documentation is very clear on the formatting/layout of said documentation. The comment raised by @Stefan-Gentz about wanting additional elements or using elements in an unsupported context just aren't ones entertained. The structure is defined for a reason - revise the context in which you want to add the content to conform to the structure.
I'm in favour of using establishes standards, provided they are appropriate. In our case, DITA as a standard won't work for our organisation. As @frameexpert mentioned, creating a custom Structured Application might we the better solution for us.