XML – DITA, DocBook, S1000D or Shipdex – Are you confused?

  • Blogs
  • SLM
  • Sort by type
  • Technologies
Published on
2017-08-25
Written by
Jonas Härdner

More and more, technical writers are realizing the value of XML as a format to use for their document creation but there is many different standards like DITA, DocBook, S1000D or Shipdex. One of the first questions facing this new user of XML is what standard of information structure to use? In our view the standard must fit the company business requirements and our experience is that a very complex data model rarely has a payback. This is a short article to try and sort out the differences and also to introduce our own “standard” Simonsoft Techdoc.

Background

We once received a question what XML standards are there for our industry? A simple Google search later and we had found some 60 different XML standards all claiming to be a just that – a standard. This can make anyone draw their breath so let’s start with the principles.
An XML document separates between Content, Style and Structure.

For the author to follow the same principles of a document the structure is controlled by a “DTD” (Document Type Definition) or “Schema”. This is a structural XML file that controls what content is allowed when, how content can be reused, what file elements are allowed when etc. In short, 2 authors that use the same DTD can always merge their documents into one without any issues of style like page breaks.

So far so good but once you look into different industry specific documentation the content will be rather different when documenting a Linux server or a Submarine. So the different industries began to form standard DTDs that fit their needs. The three most common are DITA, DocBook and S1000D (Shipdex).

Book based DTD´s – DocBook

The most common publication of all is the classic book. It has a front page an index, chapters and a back matter. Some more technical publications might also include subchapters or sections.
This is a format that everyone is comfortable with. The abstract structure of front page, title, index and chapter can be the placeholder for content regardless of which. The book as a DTD works!

There are a few standardized DTDs around the book and the most common is by far Docbook. It is a structural file that has some 20years of development and will be included in any standard XML editor you purchase. Most existing DTDs are book based with the advantages of:

  • Easy to migrate MSWord, InDesign or other documents into
  • Comprehensive and easy to learn
  • Easy to build Style sheets for

Topic-based DTD´s – DITA

As a rather sharp difference with a book based DTD there are many in the XML industry talking about topics. The by far most known standard is DITA (Darwin Information Type Architecture). The DITA standard was invented by IBM and then mainly for software documentation purpose.

To explain the topic based structure one could make an analogy of a company’s web page. Each page can then represent a topic and the complete page set the document. Now for web this sounds like a brilliant idea, but what if I need to actually produce a book. Well DITA solves this with a structural placeholder called the “book map”. In this map all topics can be linked in with the order that is wanted for the actual publication.

As you can imagine DITA makes it rather hard to migrate old content from its book form but fits extremely well for software documentation or any content that is aimed for web publish. It´s also so that writing rules must be much harder enforced since each topic must stand for itself. Remember the old game where you write a saga on a paper but each person in the class writes one paragraph and the folds the paper so the next writer only can see the last sentence. If no rules are given beforehand the saga can be rather funny in the end.

Advantages with DITA:

  • Extremely modularized that can allow for higher re-use
  • Good for software documentation and web-publish
  • Possible to translate topics individually since no context dependency Disadvantages:
  • Hard to learn
  • Costly migration
  • More complex to create Style sheet

Module based DTD´s – S1000D, ATA and Shipdex

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.

The three standards are very similar but are initiative from specific industries. S1000D – military, ATA – Commercial Airlines, Shipdex –shipping.

It is actually quite easy to understand the purpose of these standards. If an airplane manufacturer wants to assemble all the documentation about the airplane, probably more than hundred suppliers are involved. If each supplier uses their own format and way of writing it would be almost impossible to merge the information into one documentation set. It is even so that suppliers within these standards must deliver the information as XML where no style is applied. All to better serve the creation of a complete documentation set.

These standards are extremely demanding for a manufacturer to follow and so it is very rarely used outside of the mentioned industries. For suppliers only partly supplying to these industries we would even recommends using another standard and creates an export function to the needed standard.

Finally

A standard is always a standard and as such it tries to serve all. This leads to that they are all over engineered and very hard to use out of the box. For instance there are 5 different ways to tag an image in DITA. That means that reuse will take a big hit. Most projects then require a pre-phase where the standard is adopted for the company needs. This is expensive and time consuming.

Simonsoft has developed “Techdoc”. Our own version of a book based DTD but with some increase in modularization, better process descriptions and a predefined style. We have also enabled techniques to export the information for any modularized standard like Shipdex or S1000D.

All of this, in order to enable a fast XML deployment, for the medium sized company.

Good luck!
Jonas

Social media

Follow us on our social media platforms


RELATED BLOG POSTS

KeyShot 11.3 for Apple Silicon – Speed Gains and Improved Performance

Keyshot 11.3 is the latest version of Luxion's powerful 3D rendering and animation software designed for......
Read more

Materials make the world go round

The meaning of the word “material” conjures up different ideas for different people. For some, the look......
Read more

Contextual Data for IoT

Meaning of data from IoT sources If you have ever read Hitchhiker’s Guide to the Galaxy, you would know......
Read more

Using Functional Safety and Reliability for a competitive advantage

Functional Safety and Reliability is a hot topic that stimulates many discussions, depending on the......
Read more

PDSVISION and Renholmen extend their collaboration

Thoroughness drives innovation, and no detail is insignificant. Work hard to make the customers satisfied and......
Read more

Getting Started with IoT for Manufacturing

“In the beginning … the earth was formless and empty.”  – Genesis Where to begin? That is a good......
Read more

What’s new in Luxion’s Keyshot 11.2?

Keyshot 11.2! This version offers a range of powerful new features that allow users to create stunning......
Read more

PDSVISION and PTC have together helped further Electrolux Professional’s digital transformation

As a highly profitable, customer-centric business trusted by over half of Europe’s Michelin-star......
Read more

PTC Creo 9 is here – Available via PDSVISION

Creo 9  has landed with a range of updates, new features, and options designed to significantly accelerate......
Read more

PTC Creo 9 – What’s New?

There has been an addition to the PTC family of Design Solutions; PTC Creo 9 has arrived! PTC Creo 9.0 is......
Read more

Compliance within MedTech and the medical device industry

Today's product development faces several challenges, and one of the biggest challenges is regulatory......
Read more

Accelerate digitization with myPDS applications

PDSVISION launches 9 powerful applications to accelerate digitization in the manufacturing......
Read more

Short facts about KeyShot version 11.1

This version includes several new features and improvements that will make creating amazing visuals faster......
Read more

Integrate ECAD with PLM to achieve full product definition

As PLM Business Director, I meet with companies from different industries daily. It is apparent that all......
Read more

KeyShot 11 – Now Available!

The world of visualization infinitely expanded with KeyShot 11 – now available via PDSVISION KeyShot 11 is......
Read more

Enterprise Visualization in the Product and Service Lifecycle Business – one unified automated publication pipeline

As part of digital transformation roadmaps, industrial companies explore enterprise visualization to enhance......
Read more

Experts in product and packaging design company Noun chooses KeyShot and PDSVISION

Noun is a design studio based in Stockholm, Sweden, that specializes in product and packaging design. Noun......
Read more

ANSYS Discovery – Introduction

After long and sunny summer, the fall starts to kick in. Now is the time to get geared up for the winter’s......
Read more

Vuforia Instruct – Complementing PTC’s Industrial AR solutions suite!

    Vuforia, the award-winning and leading Augmented Reality reality solution-centric......
Read more

The Handyman and The Gentleman – AR #7 – Vuforia Work Instructions

To continue discussing how relevant Augmented Reality (AR) is for the industrial enterprise, in this blog, I......
Read more

Working on our ways of working – to support our customer projects in a better way

At PDSVISION we strive to be the best at what we do, and we have always been proud of our deliveries and our......
Read more

PTC Creo 8 – What’s New?

There has been an addition to the PTC family of Design Solutions, PTC Creo 8 has arrived! When an update to......
Read more

The Handyman and The Gentleman – AR #6 – Capture, Edit & Author

In my previous blogs, I have shown and discussed how the PTC Vuforia family of solutions is becoming the......
Read more

OnDosis chooses PDSVISION on their journey into improving healthcare

OnDosis develops products used for flexible and individualized dosing of oral medicines for diseases with a......
Read more

Mathcad Prime 7.0 is here!

PTC have released the seventh version of the Mathcad Prime calculation software which includes a range of......
Read more

The Handyman and The Gentleman – AR #5 – Vuforia Expert Capture – Simple, Secure and Smart

In this blog, the fifth in my series based around my Augmented Reality video series "The Handyman and The......
Read more

Creo combined with Ansys Mechanical – Your Competitive Advantage In Product Design

The challenge of designing winning products is getting more difficult by the day. The choices made in the......
Read more

The Handyman and The Gentleman – AR #4 – Vuforia Expert Capture

I’ve spoken recently in blogs on how AR applications (Augmented Reality) such as PTC Vuforia Chalk can......
Read more

Creo Parametric Behavioral Modeling Extension

Design automation for various design goals with PTC Creo Parametric Behavioral Modeling Extension......
Read more

The Handyman and The Gentleman – AR #3 – Working Hands Free

In my previous blog I explored with you how such a simple task as an onsite customer maintenance task or......
Read more

The Handyman and the Christmas StARs

"How can Augmented Reality come to my aid as I face my biggest challenge since joining PDSVISION? Making......
Read more

The Handyman and The Gentleman – AR #2 Problem Resolution

All business’ understand the importance of getting the work done correctly and to standard the first time.......
Read more

Keyshot 10 – Now Available

Keyshot 10 is here and available via PDSVISION. KeyShot 10 brings unbound creative capability to help realise......
Read more

Trimble AB Invest In Luxion Keyshot

[caption id="attachment_10854" align="alignleft" width="300"] Image: Trimble[/caption] Luxion KeyShot is the......
Read more

The Handyman and The Gentleman – AR #1 – Getting Work Done

Imagine you’re a Field Technician, sent out to a customer to perform scheduled customer maintenance.......
Read more

Ambulansproduktion and PDSVISION continue their joint journey!

Ambulansproduktion develops the markets most innovative and robust ambulances. These ambulances create safety......
Read more

Leaving Information Island

Democratizing information is a cornerstone for a successful Digital Transformation In projects that aim to......
Read more

Energy Machines and PDSVISION initiate collaboration!

Energy Machines and PDSVISION started collaboration around both CAD and PLM components, last week. This with......
Read more

The undoubted benefits of implementing a PDM system

For any product development company, the PDM System (Product Data Management) is an essential component as it......
Read more

Before you can really consider AR and VR, you need to get the conversation going!

Before you can really consider if AR and VR will have a beneficial impact on your business, you need to get......
Read more

PTC Creo Parametric ( Pro/ENGINEER) vs. Solidworks – The Second Coming

Hello, do not worry, I am not intending to discuss with you W. B. Yeat's famous poem from 1919 today! No, I......
Read more

How do I create a single part in the context of the assembly in PTC Creo Parametric?

For historical reasons, PDSVISION Germany has many customers who use Creo Elements / Direct Modelling.......
Read more

AR – Meeting the Industrial Enterprise needs in manufacturing

My clients ask, "How can AR make our production staff and manufacturing process more efficient?" Is there a......
Read more

The Need of Digital Twins to Support Circular Economy

PDSVISION has recently participated in the EU Commission funded Horizon 2020 project studying circular......
Read more

Whats new in PTC Creo 7.0?

Here in Finland, Spring returns and brings new sprouts from the ground, leaves to trees and endless sunshine......
Read more

PTC Creo vs SOLIDWORKS

Rivalry between Creo vs SolidWorks. As a senior consultant for PDSVISION I spend a lot of time with......
Read more

Getting things done remotely, in a world that almost changed overnight

Vuforia Chalk - The solution to the collaboration challenges we face within 3d design With people’s......
Read more

Ansys – More Than Just Simulation

We at PDSVISION have supplied solutions around Ansys portfolio of products for some years, especially Ansys......
Read more

5 Reasons to invest in KeyShot

Create 3D renderings, animations and interactive visuals. KeyShot is Luxions globally known stand-alone......
Read more

PDSFORUM – time well invested

PDSFORUM – time well invested "4.5 out of 5 in the score for our workshops" Participant survey "The most......
Read more

Delivering value with Augmented Reality

A conference room filled to the breaking point was the scenario when we hosted a breakfast seminar together......
Read more

Getting started with PTC Creo Simulation Live now easier than ever!

PTC Creo Simulation Live is one of the first results to come form the partnership between PTC and Ansys. It......
Read more

BoM Transformation – Product Lifecycle Data is Created in Engineering

[caption id="attachment_7471" align="alignright" width="300"] BoM Management in PTC......
Read more

Change Management – A Cornerstone

"….most design is a variation from or modification to, an already existing product or machine". (Cross,......
Read more

PTC Creo – The best CAD software on the market today

Religion, politics, what football team you cheer for, some topics can generate emotions instantly when......
Read more

Creating Inheritance Models for Manufacturing with Creo Parametric (Formerly Pro/ENGINEER)

In design, the question often arises as to how you can design so that you do not have any problems later on,......
Read more

The benefits of using myPDS Configurator

I find PTC Creo Parametric as an excellent 3D CAD solution for large, configurable assemblies. Creo......
Read more

Different Product Configuration Approaches

Product Configurators gives companies a possibility to manage product variants in an efficient way, for PTC......
Read more

Windchill 11.1 – PLM in the modern web

Windchill 11.0 has been around for the last two years. With its release PTC started a journey to renew the......
Read more

Creo 5.0 Update

The PTC Creo 5.0 release is jam packed with new features, Topology optimization studies, built in flow......
Read more

Saving Heat Treatment Steps Means Saving Costs

Cut manufacturing costs with MAGMASoft Many of our customers ask me if we can help them to cut manufacturing......
Read more

3D printing with Creo Parametric

3D printing or, a bit more technically phrased, Additive Manufacturing, may be on everyone’s lips and......
Read more

myPDS Apps – What problem do they solve?

PDSVISION has been developing for years add-on solutions for PTC software users. I am regularly asked why are......
Read more

Security in PTC Windchill – Part 2 of 2

In my last post on the theme security in Windchill I provided some general tips for creating a safer server......
Read more

Great features in Creo Simulate

Some hints on existing functionality that one might not be so familiar with and some features from Creo......
Read more

Security in PLM System Windchill – Part 1 of 2

Security is something we often seem to take for granted. The problem with this is when something goes wrong,......
Read more

Take Control of your Creo Parametric modeling

Many companies are continuously expanding their utilization of 3D CAD. Both for manufacturing material but......
Read more

Five tips from our Support

Our Support team helps our customers worldwide with our solutions, Creo (3D CAD), Windchill (PLM), Simulation......
Read more

Life as a Support Engineer at PDSVISION Support

Working as a support engineer at PDSVISION Support is a varied job and no day is like the other as you get to......
Read more

11 great improvements in Windchill 11 – Part 2 of 2

PTC Windchill 11 was launched 15th of November, the top highlights - Top down support of Find Numbers......
Read more

What is your IoT strategy?

Business leaders are today aware of the potential of the Internet of Things (IoT) to fundamentally change......
Read more

11 great improvements in Windchill 11 – Part 1 of 2

This is part 1 of my Windchill blog review of the improvements in PTC Windchill 11.0 (PTC Windchill PDMLink),......
Read more