8

I'm trying to understand the technical difference between DITA and S1000D.

Yes, I know, the common wisdom is that if you need documentation for helicopter or submarine, you should use S1000D, and if you need documentation for software, you should use DITA. While this is true, it is too shallow level of understanding.

With a lot of searching I found some articles about technical side of this difference, but still, it's completely unclear for me, probably because I never worked with DITA or S1000D before.

  • From Slideshare presentation (slide 24):

    DITA maps specify hierarchy and the relationships among the topics; they also provide the context in which keys are defined and resolved.

    S1000D Publication Modules contain references to data modules, other publication modules, or legacy data of a publication and its structure.

  • From one article, which in turn an excerpt from the book:

    This points to one of the key differences between DITA and S1000D, which is the granularity of the level of reuse. While S1000D encourages reuse at the data module level (roughly equivalent to a topic within DITA), it does not have mechanisms for intra-data module reuse.

    My note: The word "intra" applied to "data module", not "data".

  • From another article:

    Both S1000D and DITA use the same underlying concepts and aims ... (from here to the end of the article).

  • Also, in one another article it is clearly stated that DITA and S1000D are assuming completely different types of authoring. DITA is topic-based, while S1000D is module-based:

    There is one more major alternative to the book based and topic based DTD and that is to chop up the XML content in modules. In our meaning not that far from the topic based but it is really about linking it to the product structure.

    My note: Well, from what I read about there are different types of modules in S1000D. We have "data modules" which are something similar DITA's "topics" and we have "publishing modules" which are something similar to DITA's "maps". For this reason, it's not clear which one of them implied within "modular-based authoring" term. Authoring based on data modules or authoring based on publishing modules? Argh.

So, what is the techinical difference between DITA and S1000D? How DITA's topic-based approach differs from S1000D's module-based approach? Does it all mean that S1000D is not so flexible in content reuse as DITA (see second quote in my post), and how exactly this unflexibility looks, in comparison with DITA?

5
+150

Topic-based authoring is a kind of modular authoring. Modular authoring is simply any kind of authoring where content is written in reusable pieces (modules), which may then be combined to form one or more publications, instead of writing a publication as a single unit. One advantage of this approach is that when two publications contain the same information, you only need to update that information in one place. DITA calls these pieces topics, and S1000D calls these pieces data modules.

S1000D is more of a whole process for creating technical documentation. The specification includes XML schemas which are used for the actual authoring of content, but it also covers much more, such as data exchange, quality assurance, version control, presentation in both page-based and electronic formats, etc.

That said, the S1000D schemas are more rigid than DITA. DITA allows a lot more customization of the schemas through specialization. S1000D really only allows you to add extra constraints on top of the schemas by use of Business Rules Exchange (BREX) data modules, and a tool which can validate S1000D modules against a BREX.

For example, the schemas allow the values of attribute emphasisType to be "em01" thru "em99", but you can limit your project to only using "em01" (bold) and "em02" (italics) with a BREX rule:

<structureObjectRule>
  <objectPath allowedObjectFlag="2">//@emphasisType</objectPath>
  <objectUse>The value of attribute emphasisType must be em01 (bold) or em02 (italics)</objectUse>
  <objectValue valueForm="single" valueAllowed="em01">bold</objectValue>
  <objectValue valueForm="single" valueAllowed="em02">italics</objectValue>
</structureObjectRule>

The BREX validation tool would present the erroneous XML branch to the user with the objectUse message if they used "em03" for example.

S1000D also has a very particular paradigm for the creation of modules, using a Standard Numbering System (SNS) and information codes. The SNS tells you what component of the product that module is about, and the information code tells you what kind of information the module contains about the component.

For example, if you define the SNS 32-00-00 to mean "Landing gear", and you take the information code 040 which means "Description", you get the data module "DMC-PLANE-32-00-00-00A-040A-D" which is titled "Landing gear - Description".

To hopefully clear up your confusion about publication modules, they define the structure of a publication only. They list what data modules will appear in the publication, and in what order:

<pm>
  <identAndStatusSection>
    <!-- snip -->
  </identAndStatusSection>
  <content>
    <pmEntry>
      <dmRef>
        <dmRefIdent>
          <dmCode modelIdentCode="PLANE" systemDiffCode="A" systemCode="00" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="001" infoCodeVariant="A" itemLocationCode="D"/>
        </dmRefIdent>
        <dmRefAddressItems>
          <dmTitle>
            <techName>Aeroplane</techName>
            <infoName>Title page</infoName>
          </dmTitle>
        </dmRefAddressItems>
      </dmRef>
      <!-- more data module references... -->
      <dmRef>
        <dmRefIdent>
          <dmCode modelIdentCode="PLANE" systemDiffCode="A" systemCode="32" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
        </dmRefIdent>
        <dmRefAddressItems>
          <dmTitle>
            <techName>Landing gear</techName>
            <infoName>Description</infoName>
          </dmTitle>
        </dmRefAddressItems>
      </dmRef>
    </pmEntry>
  </content>
</pm>

You can also create hierarchical groups by nesting <pmEntry> elements and titling them with <pmEntryTitle>

Lastly, I'd like to slightly correct one thing you quoted:

This points to one of the key differences between DITA and S1000D, which is the granularity of the level of reuse. While S1000D encourages reuse at the data module level (roughly equivalent to a topic within DITA), it does not have mechanisms for intra-data module reuse.

S1000D does have intra-data module reuse, via Common Information Repositories (CIR) (or Technical Information Repositories (TIR) pre-Issue 4.1). But these are limited to specific kinds of information such as parts information, common warnings and cautions, functional item numbers, etc., for which the specification has defined a CIR. DITA still has more granular reuse, because with the conref mechanism and XInclude, you can reference just about any element in any document. Although XInclude is not specific to DITA, the S1000D schemas do not allow the use of it as of the latest issue (4.2).

CIR example:

You have a common part called the "ABC connector". Your parts repository contains details about it:

<partSpec>
  <partIdent manufacturerCodeValue="12345" partNumberValue="ABC"/>
  <itemIdentData>
    <descrForPart>10 mm ABC connector</descrForPart>
    <partKeyword>connector</partKeyword>
    <shortName>ABC connector</shortName>
  </itemIdentData>
</partSpec>

In a procedural data module where this connector is required as a spare part, instead of duplicating the above information, you can reference it:

<reqSpares>
  <spareDescrGroup>
    <spareDescr>
      <partRef manufacturerCodeValue="12345" partNumberValue="ABC"/>
      <reqQuantity>1</reqQuantity>
    </spareDescr>
  </spareDescrGroup>
</reqSpares>

This data module is said to be CIR-dependent because it only contains a reference to the part. You have two main options for delivering it:

  1. Resolve the CIR reference by copying the information from the parts CIR in to the data module. This could be an automated process at publish time, for example. Afterwards, the data module is said to be standalone.
  2. Distribute the CIR with the data module. This is more common when you're publishing to an Interactive Electronic Technical Publication (IETP) viewer that can fetch the information from the CIR at run-time.
5

Few short publications, that summarize the differences, and guide to a decision:

1) S1000D or DITA – Which Should You Use? ...A dude with 30+ years in the business of aerospace and software development provides the same "common wisdom" that you mentioned, and emphasizes the different philosophy of DITA "flexibility" vs S1000D "standard" (the "Theory X and Theory Y" part). ..."S1000D implementers dream of the flexibility of DITA, but understand why they’re locked into the S1000D “standard”."

2) DITA vs S1000D - Which One Is Right For Me? ...Specifications, including the differences, benefits and disadvantages to working with each. From an aerospace-industry oriented source.

3) DITA and software development: Ten reasons why DITA and Agile are made for each other and a match for software development teams: Starts from "Topic-based approach" (DITA topic), "Task topic type" (DITA General task topic), and more.

4) Another publication states "What sets DITA apart" (from S1000D). ...is "its specializations" and "inherited versatility". ...Example: IBM developerWorks: Specializing topic types in DITA: Creating new topic-based document types.

In addition:

  • Adobe FrameMaker can be used to handle DITA projects.
  • Adobe FrameMaker comes ready for DITA out of the box.
  • Adobe promotes DITA (Google it: Adobe DITA World)

--

I emailed Keith Schengili-Roberts from IXIASOFT (of publication number 3) about the technical-differences and his answer was a chapter from his book, that you already mentioned. I repeat:

"S1000D does include a mechanism for the reuse of content, known as data modules. These data modules can contain text and/or graphic content, and can be ‘plugged in’ where needed within any S1000D document. There are a number of data module types, roughly analogous to the DITA topic types, and include information that is specific for creating checklists, service bulletins, front matter, parts data, wiring data, learning modules, procedures, faults, information for the crew/operator and more. As you can see from this short list, many of the data modules were originally tailored for specific purposes within the aerospace sector which would not apply in more general circumstances." ... "The specificity of some of its module types to the aerospace and related industries limits the appeal for its adoption outside of these sectors."

(In S1000D) "Each data module comes with a unique identifier, called the Data Module Code, which is designed in part as a mechanism for ensuring that the same module do not appear more than once within a single document. This points to one of the key differences between DITA and S1000D, which is the granularity of the level of reuse. While S1000D encourages reuse at the data module level (roughly equivalent to a topic within DITA), it does not have mechanisms for intra-data module reuse."

(In DITA) "One of the chief differentiators of DITA when compared to the other documentation standards available is the ability to reuse content at both granular (i.e. word, phrase, sentence, topic) and topic/chapter levels. From a practical perspective, it is these multiple stages of reuse that come into play into making DITA a popular standard, making possible the additional advantages of consistent messaging, lower localization costs, and greater efficiencies as writers reuse existing content instead of having to recreate it."

  • So, as I understand, here are key points: 1) Topics in DITA are something very similar to data modules in S1000D, 2) In DITA it is possible to reuse content inside topics as well as reuse topics themselves, 3) In S1000D it is possible to reuse content inside data modules, but it is not possible to reuse data modules themselves? – john c. j. Jul 30 '18 at 14:20
  • That's what Keith Schengili-Roberts states. There is also the "specialization" (Publication 4). Keith Schengili-Roberts adds that the specificity of some of S1000D module types to the aerospace and related industries limits the appeal for its adoption outside of these sectors. Publication 4 adds that: "DITA was created for technical systems documentation and is in the forefront for program and engineering documentation in the IT industry. This fact is further substantiated by DITA originating in IBM and having prominent supporters like Microsoft, Intel, Cisco, Oracle, and SAP." – Amit G. Jul 30 '18 at 16:33
  • "While S1000D encourages reuse at the data module level (roughly equivalent to a topic within DITA), it does not have mechanisms for intra-data module reuse." - So, the point 3 of my first comment wasn't correct, as I realized now. It works in other way round. That's mean, in S1000D it's possible to reuse data modules, but it's not possible (well, it's possible, but with some restrictions, as Kibukj described) to reuse content inside them. – john c. j. Aug 2 '18 at 19:31
  • @johnc.j. It described in my answer: "One of the chief differentiators of DITA when compared to S1000D is the ability to reuse content at both granular (i.e. word, phrase, sentence, etc.) and topic/chapter levels." + the Specializing topic types in DITA that sets DITA apart" from S1000D. – Amit G. Aug 2 '18 at 20:47
4

Yes, these sorts of comparisons between systems are very difficult, essentially because there is no independent definition of terms like topic and module outside of the particular systems that use them. In other words, both systems, as well as several other similar systems, use similar terms to describe their models and functions quite independent of each other. It is not like comparing two minivans from different manufacturers. There is no agreed definition of horsepower or steering wheel or door that you can use to compare them with. You basically have to get down to the nitty gritty implementation details and see how they differ.

In my forthcoming book, Structured Writing: Rhetoric and Process, I try to provide some tool-neutral terminology for talking about structured writing methods, largely by avoiding these confusing terms altogether. When it comes to terms like module and topic, I suggest four types of information block: the semantic block (objects that writers would recognize independent of a structured writing system, like lists and tables), the structural block (the things semantic blocks are made from), the information typing block (the kind of blocks found in information typing theory, such as Information Mapping), and the rhetorical block (the thing that is actually meant to be read).

But even with those terms, I could not tell you which of these things a DITA topic is, because the term is just not well defined. Depending on how you use it, it could be any one of my four types. I don't know S1000D well enough to say how their idea of a module would fit, but I suspect it would be similarly vague.

Content, fundamentally, has fuzzy boundaries. It is all the stuff that does not fit neatly into data structures. Structured writing tries to make content look enough like a data structure to be processable by algorithms, but if you try to do that in a general way, you end up making your containers pretty fuzzy in order to fit around all the varied things they have to contain. And thus those containers tend to defy both characterization and comparison.

If you actually want containers that can be defined and compared with any degree of strictness, you have to be much more specific to the subject matter, audience, and type of document you are dealing with.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.