contents
HTML-formatted text of the document. This is not required, but is an opportunity to provide additional unstructured information about the topic.
- Attributes: None
A manual can describe a collection of procedures, or just a single procedure. An example service manual for a Dell laptop might include a dozen procedures, technical descriptions of the device, or hundreds of photos and videos. The manual could be accessed by reading a .omanual file on a desktop computer, or on a tablet or smartphone via a web service.
The common oManual data format can be expressed as XML (useful for interoperability with legacy data in formats such as DITA) or made available over a web API using mobile-friendly JSON.
This document describes topic metadata. A topic can be anything you would write step-by-step procedures about, such as a manufactured object, or device.
The root of an oManual topic.
Contains the title of the topic document (which may differ from the topic name).
Text should contain the canonical name of the topic.
A flag or informational note about the topic. The text field contains a full text notice of what this flag means to the user.
A single category the topic belongs to. There is not currently a global list of documentation categories.
A reference to an external mailing list, Q&A site, message board - anywhere your audience can find additional troubleshooting information. For example, iFixit Answers and Stack Overflow are two examples of solution providers.
HTML-formatted text of the document. This is not required, but is an opportunity to provide additional unstructured information about the topic.
A procedure is a structured collection of steps. Each must include text and media. For consistency of display, we recommend each step consist of 1-3 images or one rich media object, as well as no more than eight lines of text.
The root of an oManual procedure.
Format (YYYY-MM-DDThh:mm:ss) - Date and time this procedure was last updated. This element can be useful for checking if there are updates to the guide. The modified_date is the same as the created_on date in a new guide.
Format (YYYY-MM-DDThh:mm:ss) - Date and time when this procedure was first created.
Contains the title of the procedure.
A text field that contains less than or equal to 255 characters describing the procedure.
The path to the image introducing the procedure. Image is required, so if you do not have an additional primary image, duplicate the first image of the procedure. The path is relative to the directory containing this XML file.
Author of the procedure. In the case of multiple authors, this would be the primary author or maintainer of the procedure.
A human readable description of how long the procedure takes. ex: 15 minutes
A determination of the difficulty of the procedure for your target audience. Please choose from one of these five options:
Simplified HTML formatted text introducing the procedure. This could describe anything from how to set up for the procedure to an introduction of the procedures subject matter. There is no length limit, but we suggest limiting this to no more than 2-3 paragraphs.
A container for the introduction's media. It can contain one of these: 1-3 images OR a video OR a remote oEmbed object.
Image to include with the introduction.
Describes the different possible encodings for the video. Different web browsers, mobile devices and operating systems require different formats to play videos. Because of this, there can be 1 to N number of encodings.
Default image for the video. Usually a descriptive image that's shown to display the video, before the video is loaded or played.
Detailed information about the original video source. This is useful if you have encoded a video from a different codec and format and would like to store information about the original video or access additional information, such as frame_rate or audio_codec which would stay the same between different encodings. This element is flexible, meaning it can include any attributes in addition to the ones described below.
Remote embed to include with the introduction.
1.0.maxwidth and maxheight parameters. If this parameter is present, thumbnail_width and thumbnail_height must also be present.thumbnail_url and thumbnail_height must also be present.thumbnail_url and thumbnail_width must also be present.A required or suggested tool or implement. Use a name common to all of your procedures and specify variations using the type attribute.
A part, material, or ingredient used in the procedure. Use a name common to all of your procedures and specify variations using the type attribute.
External source used for sourcing and aquiring this part. Could be an e-commerce site, brick and mortar store, procedure or full oManual.
A flag or informational note about the procedure. The text field contains a full text notice of what this flag means to the user.
A document attached to the procedure. The text for this element should be the filename of the attached document.
A collection of procedures that must be completed prior to starting this procedure.
The title of a prerequisite procedure. Prerequisite procedures should be written such that steps can be inlined directly into this procedure. You can see an example of this with the prerequisite implementation on iFixit.
The step. Contains the line, object, and image elements.
Lines of text belonging to this step. We recommend a step not have more than eight lines, and that each line not exceed 500 characters. It is best to think of each line as a discrete piece of information or instruction.
A bullet line of text in the step or paragraph of instructions. Recommended not to exceed 500 characters.
A container for the step media. Each step can have one of these: 1-3 images OR a video OR a remote oEmbed object.
Image to include with this step.
Describes the different possible encodings for the video. Different web browsers, mobile devices and operating systems require different formats to play videos. Because of this, there can be 1 to N number of encodings.
Default image for the video. Usually a descriptive image that's shown to display the video, before the video is loaded or played.
Detailed information about the original video source. This is useful if you have encoded a video from a different codec and format and would like to store information about the original video or access additional information, such as frame_rate or audio_codec which would stay the same between different encodings. This element is flexible, meaning it can include any attributes in addition to the ones described below.
Remote embed to include with this step. Each embed can include the same fields specified by the oEmbed spec.
1.0.maxwidth and maxheight parameters. If this parameter is present, thumbnail_width and thumbnail_height must also be present.thumbnail_url and thumbnail_height must also be present.thumbnail_url and thumbnail_width must also be present.
The .omanual file format is an XML-based file
package which can be used to easily package, distribute, view and
import your data and referenced media files.
These files are compressed and packaged using the .ZIP file
format, which is an industry standard for cross-platform data exchange and
storage.
File examples and schema definition (XSD) files are available below to validate your own oManual XML documents.
oManual packages must have a file extension of '.omanual' and should be structured as shown below.
The package manifest is an XML description of the oManual package contents. This includes the list of procedures and a list of attached documents in the /media folder of the .omanual package.
Note: This is not a complete listing of package contents since each subfile may additionally reference its own media.
The root of an oManual manifest.
Individual procedure element. A short description of the procedure that's contained within the oManual package. The corresponding file in the package has the filename procedure-{id}.xml.
A document included in the package. The text for this element should be the absolute path to the document.
The API specification is designed to provide a simple way to expose your oManual resources to other services or devices through simple REST API endpoints. API endpoints should be relative to a base server address (eg. http://www.ifixit.com/api).
Returns a list of all procedures sorted by procedureid.
Comma-delimited list of procedureids identifying the procedures to return.
Return only guides of the specified type. For example, to get all teardowns, you can query /guides?filter=teardown&limit=10000
Return the guides in ascending or descending alphabetical order.
The number of procedures to skip from the beginning. Range: [0, infinity). Defaults to 0.
The maximum number of procedures to include in the response. Range: [1, 200]. Defaults to 20.
Returns a comprehensive list of attributes about a procedure.
If set, the response will not include steps from prerequisite procedures. By default prerequisite procedure steps are inlined with the current procedure's steps.
Possible values: JSON or XML.
Returns a flat list of the category names on the site.
The number of categories to skip from the beginning. Range: [0, infinity). Defaults to 0.
The maximum number of categories to include in the response. Range: [1, 200]. Defaults to 20.
Returns a comprehensive list of attributes about a category, including the full text of the main category page and a list of all procedures. The category name must be URL encoded.
Possible values: JSON or XML.
Where specified, formatted text within the standard may use simplified XHTML. The text must validate and should not be escaped via CDATA. Simplified HTML is defined as these HTML tags:
<p><a><strong><em><h1><h2><h3><h4><h5><h6><tt><pre><code><br><ul><li><sub><sup><del><ins><div>With these attributes:
id, class, href, style, rel, title, targetPaths can be either either an URI to a web resource or a local path, absolute from the base of the package. Local paths are only allowed for offline packages. Fully qualified URIs are always allowed.
Design content for display. Yes, you can stuff really long paragraphs into a single step. But it won't look good!
Make life easy for programmers. The most efficient file package will only have a single copy of each image, but providing urls to pre-rendered thumbnails makes designing mobile applications fast.