Implementing_S1000D_Best_Business_Practices_Means_Understanding_Your
- 1. S1000D User Forum San Antonio, Texas June 23-27, 2014 Presented by: Mike Cook – SDL – Structured Content Technologies Division
- 2. Best Business Practices S1000D is all about best business practices. It’s an assemblage of various capabilities and features to help businesses achieve greater quality and functionality with the possible benefit of reducing costs. To leverage the best business practices of S1000D, you must know your business and how to make S1000D augment your business practices. Leveraging the capabilities of S1000D means you must know how to integrate it into your business – which means you must know your business processes intimately. One of the primary intents of S1000D is to support the development of IETP content.
- 3. Organizing content may not be the same now Are you sure you should continue to organize content the same way you have in the past? The specification is leading us to a homogenous mass of data without artificial boundaries so it can be displayed in an IETP. Discrete publications are becoming an optional method of assembling content and are an artificial construct that may be getting in the way of making your content easier to access. If you’re tracking and selling your publications, what method should you use in the future - part numbers for publications or part numbers for IETPs? Use the 00-40-xx SNS codes to your advantage – combined with the <systemBreakdownCode> you can use automation to create your Publication Modules and related front matter.
- 4. Applicability changes how you use some code structures Are you certain the configuration of your content is logical and not physical? Regardless, stay away from the zonal SNS methodology that forces a physical decomposition of your product. A zonal SNS and applicability don’t work well together. The system difference code is not needed if your project elects to use applicability. The primary intent of the disassembly code becomes moot when applicability is enabled. Coding a physical configuration destroys the intent of the SNS and the logical code structure of the DMC. A logical configuration of the product is supported by the SNS, techname of the DMC, and applicability. Consider the left to right DMC hierarchy of codes and related granularity used to assemble a techname. Zonal SNS structure corrupts the intent of applicability and the hierarchical decomposition of the DMC. A Zonal SNS introduces configuration problems for subsequent derivatives of the product (replication of data modules as opposed to the use of “typical”). For example, wiring, hydraulics, pneumatics usually span zones.
- 5. Using the Data Module Extension code to show ownership of content Do you know if you have a problem indicating the ownership of content for customers – due to customization of content for various customers? The Data Module Extension (DME) code can solve this problem, but may cause a change in your publishing practices. You can indicate the source of the original data module, but it can also be used (and abused) to make Frankenstein data modules. Using DME codes requires a different use of data module Issue numbering when using digital data delivery (when not delivering an IETP). The source DMs may have issue numbers different from the delivered DMs for various customers. Publishing to a website or IETP is very different from publishing raw XML (digital data delivery). The number of customers who want raw XML is growing. You have control over an IETP if you publish it. If you hand raw files over to someone else, there are no guarantees they will present information the way you intended it to be viewed. Moving to a DME paradigm allows you to indicate ownership of the data and who it was created for such that you can wash your hands of the presentation layer.
- 6. Integrating business rules from on high Do layered business rules fit your business model? If so, is it going to cost you extra to implement? Can you manage more than one customer’s BREX DM at a time (multiple customers with differing requirements)? Rule checks and attribute enumerations Can you afford to have multiple rule checks for the same element or attribute due to multiple requirements from different customers? Do different customers require custom enumerations that are different? (good luck making that work) Protecting your project from the contract and sales groups Did your contract or sales groups put you in a bind by agreeing to something you can’t deliver? Make sure your contracts and sales teams are aware of what your business is capable of supporting – regardless of whether or not it’s S1000D or some other paradigm.
- 7. Getting what you want from suppliers Are you sure you’re managing graphics legally? Be sure you know who has the right to modify graphics. There are potential problems with changing file names, modifying a graphic, or even a requirement to indicate attribution if the graphics are coming from a supplier or vendor. Little things like this can lead to big lawsuits. Are you sure your authors are not accidentally plagiarizing? Copying the content from one manual sourced by one vendor or supplier into your manual can lead to significant law suits if you don’t have it written into the contract for you to copy content at your discretion. Dealing with ownership of source data (copyright, authorityDoc, authorityName) If you change the content of a data module provided to you from a vendor, you may be required to use the authorityDoc and authorityName attributes to shield the vendor/supplier – or even yourself – from potential liabilities.
- 8. Getting what you want from suppliers (cont’d) Can you still consume PDF or does it need to be S1000D now? Forcing suppliers to provide S1000D is something you’ll need to put into a contract – unless the supplier is already creating content in S1000D. Leveraging a requirement to force suppliers to source content in S1000D after they’ve been producing content in another format is not something you want to do in the middle of a project – it must be negotiated for up front as part of a contract. It also is difficult for your techpubs group to change horses in the middle of a project. Who owns what layer of the publication and what's it going to cost you? It’s surprising how many businesses mandate a requirement for a vendor or supplier to own a portion of a document they have no control over. For example, the vendor/supplier provides a sub system but the final system integrator requires the vendor/supplier to document the circuit breakers the system is powered by – but those breakers are documented in a publication controlled by the final system integrator and may change from one instance of the final system to the next. It is essential for a business providing content to know where their responsibility begins and ends. Don’t get suckered into sourcing content for which you have no control over.
- 9. S1000D is not perfect, and the same can be said about your business – for example: Do you really understand how your business creates illustrations and graphics? Do yourself a favor and don’t use the CAGE code based ICN paradigm. It WILL come back to bite you. It does not guarantee a unique ICN file name over the lifetime of the project (talk to the creator of this paradigm – his company has been bitten by this code structure). Stick to the Model ID based ICN code structure. Avoid the Zonal SNS (replication of content). Watch out for conflicting definitions (Information Set is a classic) Does your business need to use the service bulletin or front matter schemas (are you sure)? Only if you know your business and how you will need to use S1000D can you address these areas. In many cases, the contract with a customer is not read by the tech pubs group and can lead to serious repercussions later.
- 10. Do you understand your business enough to understand how to adopt features of the spec? What is a product attribute to your business? Do you need Service Bulletins? If so, how are you going to track incorporation status – do you need to? Did you know Service Bulletins are Publications and should be managed like any other manual you create? How much do you need at the beginning and how much can you add as you go? Why not make things easier and adopt the easy stuff in the specification? For example: Data Module Titling paradigm Information Code Variant definitions Reason for update and Highlights data module Automated generation of front matter etc
- 11. Thanks for attending There are many undocumented features of the specification where you are expected to read between the lines and connect the dots. A few of these capabilities were presented here but require further study if they are to be used in any business choosing to adopt these capabilities. To use S1000D you must understand your business and adapt, adjust, or tweak your business rules accordingly. A successful implementation of S1000D requires a complete understanding of how your business functions.