A little bit of history. Manuals have always included images, parts diagrams, and references to other documents. Those links and metadata are a significant part of what makes a manual effective. The internet is perfect for making these documents come alive, making it possible to connect procedures with tools and reference specifications. Unfortunately, the vast majority of manuals distributed online don't take advantage of this flexibility. PDF documents are static, have no structure to their data.
A huge amount of useful data is buried, trapped in static documents where it cannot be leveraged, built upon, and repurposed.
oManual is an XML—based data standard that solves this problem. Publishing manuals as both user—friendly PDF / HTML and machine—friendly oManual files allows for the best of both worlds: manuals that retain their ease of use, but are also easy to maintain and build upon.
oManual started when O'Reilly Media (a leading publisher of technical books) and iFixit (the free online repair manual) started searching for a data format to exchange their procedural manuals. Existing XML specifications were overly broad and convoluted, ill—suited for procedural manuals. So we created a specialized format to fill the gap.
oManual is for anyone who wants to publish manuals, whether they are repair manuals, manuals to create things, manuals to destroy things, how—to guides, work instructions, or any other type of manual which contains step by step instructions. oManual is also for developers who want a flexible format that allows them to republish content in new and exciting ways.
Manual is an “overloaded” word, and most dictionaries have outdated definitions referring to instruction books. Here's our definition: A manual is a document that teaches you how to do something. To pick a few examples, we think oManual is a good fit for reference manuals, instruction manuals, user manuals, owner's manuals, how—to manuals, survival guides, and service manuals — but that's just a start.
Traditional documentation—PDFs, Word documents, and even complex files like DITA—lives on a single computer. Establishing a 'single source of truth' for these documents requires complex document management systems. Accessing these (often very large) documents from a mobile device can be challenging, because it requires downloading the entire file up front.
Mobile applications usually download information as they need it, from an on—demand API. oManual bridges these two worlds by providing a common data format, and allowing the information to be transmitted via legacy offline files or made available as a web service. An example workflow would be to take XML DITA service manuals, convert them to oManual with an XSLT transform, then load them onto a JSON server for use by mobile applications.
oManual is not a subset of DITA, but it is straightforward to convert from oManual to DITA, or from DITA to oManual.
Don Day, the Founding Char of the DITA Technical Committee and DITA Expert, wrote a dita-to-omanual converter to bring your DITA documents over to oManual. One note of caution: 'round—tripping' content from DITA to oManual and back again is not recommended, because oManual does not fully support all of DITA. This simplicity of oManual is a feature, not a bug.
As of right now, Dozuki is the only software platform that can read and write oManual packages. We are working with a number of companies to get this standard implemented as part of their software platforms, such as XMetaL and Oxygen XML.
iFixit has released open source apps that implement oManual's JSON API for Android, iOS, as well as Windows 8 and Phone 8.
Absolutely. We will be expanding the standard as needed. Our driving principles:
To get involved, join our Github Project page. From there you can submit bugs, discuss features and submit code. If you have an oManual integration or module or want to know how you can help, drop us an email!