Understanding S1000D Business Rules

Transcription

1 WHITE PAPER Understanding S1000D Business Rules Avoid costly mistakes and use Business Rules to facilitate a successful S1000D implementation

2 Table of contents Introduction The Basic S1000D Process S1000D Business Rules deined The S1000D Business Rules Project Why S1000D Business Rules Projects fail Ensuring Business Rules Project Success Conclusion

3 Understanding S1000D Business Rules S1000D - AN EVOLVING SPECIFICATION FOR COMPLEX INDUSTRIES If you are working in the ield of aerospace or defense technical publications, it s likely that you ve been hearing a lot about S1000D in the last few years. Or maybe you have already begun using this speciication in your organization. In fact, both civil aviation and defense organizations worldwide are joining the European defense industry in the adoption of S1000D an international speciication for the procureme nt and production of technical publications. There are many reasons why the S1000D speciication has been so widely adopted and extended to include air, land, and sea projects. Because S1000D is based on XML, the data will support signiicant automation as well as being system- and device-independent. Because S1000D is modular, it facilitates content reuse and seamless data interchange between organizations. S1000D covers the entire lifecycle of technical documentation: planning and management, production and data exchange, and distribution and use. For this reason, S1000D provides a very effective way to ensure that technical publications procured for a product such as an aircraft or submarine will meet the many and varied requirements for that product. THE PURPOSE OF S1000D BUSINESS RULES However, as S1000D has evolved to support multinational customers across both military and civil programs, it has also become signiicantly more complex and lexible than initially intended. And as the complexity and lexibility have grown, so has the requirement to document and enforce rules to ensure that projects adhere to a deined set of variables for authoring, interchange, and delivery. Sound, documented guidance for implementing S1000D within projects is absolutely critical to ensure data interoperability and consistency, and to support delivery according to customer requirements. This is the purpose of S1000D Business Rules. As S1000D has evolved to support multinational customers across both military and civil programs, it has become more complex and lexible than initially intended. As the complexity and lexibility have grown, it has become necessary to provide guidance for implementing S1000D at the project level. This is where S1000D Business Rules come into play. This White Paper explains how S1000D Business Rules are used to facilitate a successful S1000D implementation and provides guidance on how to approach Business Rule development. It explains the difference between Business Rules and BREX and provides tips on how to avoid some common and costly mistakes when developing your S1000D Business Rules. 3

4 The Basic S1000D Process An important key to successful S1000D Business Rule development is ensuring that everyone on your team understands the basic S1000D process for creating, managing, interchanging, and publishing data. This is often overlooked by newcomers to the speciication, and can result in false starts and wasted effort. FIRST STEP As depicted in the diagram below from the S1000D speciication, the very irst step in any new S1000D project is to customize S1000D to meet customer requirements. To reiterate, this is the very irst step in any S1000D project. This means that it should be done before you ve signed partner or customer contracts and before you start writing data modules. Too often projects have gotten off to a bad start because they failed to understand this concept and did not follow the process prescribed by the S1000D speciication. If you are lucky enough to be part of a project that already has some Business Rules established, you ll escape much of the signiicant effort involved with starting an S1000D project from scratch. If you are part of a larger project or program, coordinate with your partners or parent organization to get started they may have Business Rules you will need to use. FIGURE 1 - BASIC S1000D PROCESS 4

5 LEARN FROM OTHERS If your project does not have any Business Rules, see if you can build off existing efforts in your industry. Join S1000D user groups and learn from others who have previous S1000D experience. Rather than risk an expensive false start, consider professional consulting from an industry expert who has developed S1000D Business Rules before and can help you do it right the irst time. Business Rules Deined As deined by S1000D, Business Rules are decisions made by a project or organization about how to implement S1000D. These decisions cover all aspects of S1000D and are not limited to authoring and illustrating. This means that Business Rules can also address issues that are not deined in the S1000D speciication for example, rules related to how S1000D interfaces with other standards and business processes that are related to its implementation. EXAMPLES OF S1000D USERS AROUND THE GLOBE BAE Systems, Delta Airlines, Cargotec, Saab AB, Boeing, Airbus, Mitsubishi, Grimaldi Group, RSK MiG, MAN Diesel, RAF, Raytheon, multiple military and defense logistics organizations such as German MoD, Danish DLO, Norwegian DLO, Finnish Navy, US Army, US Navy and numerous others. And the list keeps growing! S1000D BUSINESS RULES RATIONALE The creation of Business Rules serves as a focal activity for an integrated design team involving documentation, development, usability, graphic design, and other groups. The purpose of Business Rules is to describe the guidelines, standards and methods for ensuring consistency across all members of an S1000D project, therefore ensuring consistency across the entire product and content delivery. Business Rules also serve as a useful training resource for new members of a technical publications team. Like a style guide, Business Rules provide all the rules for content creation, management, publishing and delivery, so a wise publications manager will require every new author to read the entire set of Business Rules before writing their irst piece of content. Finally, Business Rules can be referred to in a project s contractual documentation to establish the rules of engagement between project partners and customers. Using well-written S1000D Business Rules, every part of the documentation project is well understood and there s nothing left to interpretation. BUSINESS RULES VS. BREX These two key terms are often misunderstood and confused by newcomers to S1000D, so some clariication and explanation is needed here. BREX? BUSINESS RULES Business Rules are simply a document that is written to capture decisions 5

6 (and your rationale for those decisions) made in respect to your S1000D implementation. The Business Rules document is often lengthy and sometimes consists of multiple documents, depending on the method you choose for organizing your Business Rules. In fact, Business Rules documents aren t really a new concept. They contain the same type of information that was traditionally captured in: Technical Publications plans Author s style guides Graphics guides Presentation and publishing guidelines QA and in-process review guides Customer acceptance documents and protocols Document management plans Publication type speciications On the other hand, a BREX or Business Rules EXchange is an S1000D Data Module encoded in XML and used as a method to formally specify and exchange project-speciic Business Rules between parties. The BREX often resides in your CSDB (Common Source Data Base) and is used to aid in the validation of your XML content. It can contain: BUSINESS RULES SOURCES S1000D Business Rules documents contains information from various plans and guides. speciications of the S1000D Standard Numbering System speciications of XML elements and attributes that must or must not be applied to XML content deinitions of which values are allowed/used for speciied elements and/or attributes and how those values are interpreted descriptions of the purpose of markup elements and attri butes A project or organization must decide if it needs to develop project speciic Business Rules and, if applicable, develop its own BREX data module. Once a project BREX has been developed, every S1000D data module must contain a pointer back to the BREX for that project. The BREX provides your CSDB with the means to enforce some, but not all Business Rules during authoring and/or check-in to the repository. For example, a Business Rule such as, The attribute releaseevent shall not be used can be enforced by a CSDB; but a Business Rule such as, Any combination of control settings that will create a hazard to personnel shall be preceded by a warning cannot be enforced by a CSDB. This is because the latter Business Rule requires a human to determine what constitutes a hazard to personnel while the former simply precludes the use of an XML attribute. BUSINESS RULES EXCHANGE BREX is an S1000D Data Module encoded in XML used to specify and exchange Business Rules between parties. 6

7 The S1000D Business Rules Project BUSINESS RULES PROJECT TEAM The irst step in Business Rules development is to select stakeholders who can contribute in substantive and political ways. As with any project, consensus building is as important as technical expertise. When selecting members of the Business Rules team it should be made up of the following skill sets: Subject Matter Experts (SME) representing your various content types S1000D Business Rules project manager Graphics experts Web delivery team Project partners and suppliers THE TEAM These stakeholders will serve as evangelists for the Business Rules and the process for ensuring consistency. TACKLE CRITICAL ISSUES FIRST For a whole range of reasons, Business Rules can be very complex so it is imperative that they be deined and agreed upon, preferably before any content is produced. Unfortunately, this isn t always realistic, so at least try to cover the most critical items irst. These important items might include: CRITICAL ITEMS! Which Issue of S1000D will we be using? Have we registered all of our MOI codes? What SNS structures will we use? Do we need to modify/ create our own? What Information Codes will we use? Are there Information Codes missing? What Data Module types will we use? What is our end deliverable? Will we deliver IETP, Paper, XML? How do we intend to use applicability? What are our graphics formats and will we create 3D? These high level Business Rules decisions can go a long way toward helping your writers, coordinators, partners and suppliers reduce the anxiety associated with a new S1000D project. 7

8 BUSINESS RULES DOCUMENT ORGANIZATION Once your Business Rules project team is assembled, you will need to decide how to organize your Business Rules and determine how many documents you ll need to fully describe your decisions. The two basic approaches are described below: 1. S1000D Headings and Structure Create a set of documents that mimic the chapter breakdown in S1000D. These provide a logical breakdown and provide an easy way to navigate both the Business Rules and S1000D since they are organized in exactly the same way: HEADINGS AND STRUCTURE With a logical chapter breakdown you can easily navigate both the Business Rules and S1000D. Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Chapter 6 Introduction to the speciication Documentation process Information generation Information management Information sets and publications Information presentation/use Chapter 7 Information processing Standard numbering systems, information codes and learn codes Chapter 8 Chapter 9 Terms and data dictionary 2. Business Rule Categories S1000D now includes a concept called Business Rule categories. Grouping your Business Rules into these categories helps with standardization and scope: BUSINESS RULES CATEGORIES Group your Business Rules in categories and ease the standardization and scope. BR category 1 BR category 2 BR category 3 BR category 4 BR category 5 BR category 6 BR category 7 BR category 8 BR category 9 BR category 10 General Product deinition Maintenance philosophy and Concepts of operation Security Business process Data creation Data exchange Data integrity and management Legacy data Data output 8

9 BUSINESS RULES DECISION POINTS Whichever approach your project decides to use, the next step is to comb through the S1000D speciication to determine which decisions need to be made. To do this, you will focus on the S1000D Business Rule Decision Points or BRDPs. These BRDPs are documented primarily in Section 3 of the S1000D speciication although they can appear anywhere a decision of some sort needs to be made. When one or more Business Rule decisions are required, you will see the words Business rule decisions followed by a description of the decision(s) that need to be made. If a Business Rule Decision Point has not been identiied for a given section, it will state: None identiied. DECISION POINTS Use the S1000D speciication as a guide when determining which decisions need to be made. Below are two examples of what you will ind when looking for BRDPs in the S1000D speciication: FIGURE 2 - CHAPTER 3 BRDP EXAMPLE FIGURE 3 - NONE IDENTIFIED BRDP EXAMPLE Continuing to use the S1000D speciication as a guide, your Business Rules Project Team can now document each decision according to the organization scheme you ve selected. You are now on your way to having a set of S1000D Business Rules for your project! 9

10 Why S1000D Business Rules Projects Sometimes FaiL - 3 Common Mistakes There are three common mistakes we see when organizations begin implementing S1000D and developing Business Rules: MISTAKE #1 INSUFFICIENT PRIORITIZATION FOR BUSINESS RULE DEVELOPMENT More often than not, S1000D projects fail because organizations haven t dedicated adequate staff time to the project and fail to make Business Rules development a priority. Some technical publications managers incorrectly assume that Business Rule development is something that can be done during downtime or only once in a while. Key team members continue to work on their daytime jobs and no one gives their full attention to the project. When this happens, inconsistent data and missed deadlines are often the result. WATCH OUT! Avoid the common mistakes and make your S1000D Business Rules project a success. This is a common scenario because the S1000D Business Rules project team is going to be made up of people who are also important to your current documentation production processes. For this reason, it s important that S1000D Business Rules development be given a high priority with time carved out on a daily or weekly basis to work on them. The frequency and duration of your Business Rule development activities will be wholly dependent on your internal schedule for S1000D production but it s important to avoid long periods of inactivity. Business Rule development requires focused activity, otherwise project momentum and direction is lost and it becomes necessary to continually review the development process and previous decisions that were already documented. This can result in a painfully slow development process and can cause your team to lose focus and motivation. MISTAKE #2 INCORRECTLY SCOPING THE BUSINESS RULES DEVELOPMENT ACTIVITY Another common mistake made by Business Rules project teams is failing to properly scope the effort to develop a comprehensive set of S1000D Business Rules. If you go through the speciication and look at the BRDPs, it s easy to fall into the trap of thinking that Business Rules can be developed in a matter of several weeks. After all, there are a inite number of decision points and it seems entirely reasonable to think each of these decisions can be made in a matter of minutes. But the fact of the matter is that most Business Rules are going to take 10

11 discussion and compromise, some more than others. Certain decisions may take many hours or even days to make. In some organizations, decisions will be hard-fought. Sometimes a decision isn t accepted by a team member who continues to raise it for examination again and again. In this case, it may be necessary to develop rules of engagement for the Business Rules team to ensure that forward progress is made. As you can see, this effort is actually much larger that it seems. In fact, we have found that the average amount of time to successfully develop a comprehensive set of S1000D Business Rules is between 4 and 8 months, depending on the frequency and duration of your development activities. By understanding the Business Rule development process and scoping it correctly, you will save yourself and your team a great deal of frustration and avoid a delay on one of your irst milestones toward adopting the S1000D speciication. MISTAKE #3 NOT ENSURING YOUR S1000D BUSINESS RULES PROJECT TEAM UNDERSTANDS THE SPECIFICATION Finally, the third common mistake made by many S1000D Business Rules Project Teams is thinking that S1000D is just another guidance document or publishing speciication. If this was the case, it could be used adequately as a reference document during the documentation production process. But trying to use S1000D this way is setting your team up for failure. This is because S1000D brings a fundamental change to the way we manage, write, publish and deliver information. It requires a great deal of planning and forethought to implement S1000D properly and if decisions are being made by members of a project team with a weak understanding of S1000D, they will have a long-lasting negative effect on your project for years to come. This is where you download the S1000D speciication. Make sure your team understands it. Get help if necessary! You might think you will save on costs if you have your team just read the speciication. This is important and necessary (the S1000D speciication is available for download at and it s highly encouraged that you download and read it) but many people are not able to read and understand this complex 2,759-page speciication without some sort of formal instruction to support their understanding. Furthermore, without having exposure to a CSDB (Common Source Data Base), some of the concepts and processes involved with S1000D can be dificult to work through. 11

12 Ensuring Your Project Success To ensure that your S1000D Business Rules planning, production, and implementation go as smoothly as possible, we offer the following recommendations: ENSURE SUCCESS It cannot be said too many times: Make sure that everyone on your project is familiar with the S1000D speciication. That means that there is some reading to do; and probably some training to budget. Deine and share competencies between different players on the Business Rules Project Team; apply the expertise you have in-house to the task of developing Business Rules for your project. Network with others in your industry and leverage any Business Rules that may already exist for similar projects. Deine Business Rules as early as possible to avoid rework. Update Business Rules as often as necessary. Test Business Rules by using test exchanges before they are authorized and put into effect. Involve all known and affected parties in the review and approval of the Business Rules. Authorize and enforce your Business Rules. Deine acceptance and rejection criteria for partners on your projects. At what threshold will you accept or reject data that does not conform to your Business Rules? Create and exchange Business Rule checklists that can be used by members of your project for S1000D implementations. Exchange expertise with other organizations within the S1000D community. Many organizations and individuals provide mentoring and guidance in the context of user groups and industry working groups. Follow our recommendations and you are well on the way towards a successful S1000D Business Rules implementation. DON T STRUGGLE ASK FOR HELP Finally, don t be afraid to obtain outside help. Consider assistance at the irst sign that your team is struggling, but be careful who you choose. Select a consultant who is not only an expert in S1000D but who has also worked extensively in your industry. Ensure that the consultant you work with understands your product(s), the regulatory environment(s) you work in, and the business challenges you face, so you can be guided effectively to a successful S1000D implementation. Selecting an experienced S1000D consultant will help your team stay on track. 12

13 Conclusion Carefully-designed Business Rules are vital to the success of your S1000D project. Good business rules will facilitate seamless interoperability between all the members of your team and ensure that your delivered documentation meets the needs of your customer. Make sure your S1000D Business Rules Project Team reads and understands the S1000D speciication. Obtain S1000D speciication training if needed. DO IT RIGHT THE FIRST TIME! Learn, plan, and communicate! And schedule resources! The process for developing S1000D Business Rules is simple: Make the most critical decisions irst, such as identifying the S1000D Issue your project will use, which Data Module types will be needed, how Applicability will be set, and so forth. Then decide how you will organize your Business Rules and begin going through the S1000D speciication. As your team locates each of the Business Rule Decision Points, their decisions are documented in your Business Rules document. This is the methodology typically used to develop S1000D Business Rules for any organization, whether an industry body such as the Air Transport Association or USSMG Sea Working Group, an airframe or engine OEM, an OEM supplier, or a defense or civil aviation operator. As simple as this process may be, the actual effort to develop S1000D Business Rules is anything but easy. Business Rules can address extremely complex issues and involve clariication, discussion and compromise. Make sure you consider this when scheduling resources to this important activity. Finally, here are a few things to keep in mind when it comes to S1000D Business Rules: The more thorough your planning is, the more effective your implementation will be Communication between all team members is absolutely vital to the success of your S1000D Business Rules project While good Business Rules will facilitate data compatibility and conformance, bad Business Rules are a waste of time and money It s much easier to do it right the irst time 13

14 ABOUT FLATRONS SOLUTIONS Flatirons Solutions provides consulting, technology, and outsourcing for content lifecycle management. For more than 20 years, it has served global Fortune 1000 customers in aerospace, automotive, electronics, inancial services, government, healthcare, and publishing. Its customer engagements help organizations eficiently deliver the right information, at the right time, to the right people by leveraging structured content and digital media Turning Content into Knowledge. ABOUT CORENA SUITE The CORENA Suite from Flatirons is the leading solution for content lifecycle management developed speciically for organizations that rely on mission-critical data to design, manufacture, operate, or maintain complex assets over product and service lifecycles as well as across their business networks. For more than 25 years, the world s leading airlines, aerospace manufacturers, energy companies, automotive companies, and military organizations have used the CORENA Suite to create, deliver, consume, and optimize large volumes of technical information throughout its lifecycle. Flatirons customers rely on the CORENA Suite to improve customer satisfaction, labor productivity, and asset utilization so they can maintain their competitive advantage. Info@FlatironsSolutions.com FLATIRONS REGIONAL HEADQUARTERS AMERICAS Flatirons Solutions, Inc. Irvine, CA EUROPE Flatirons A/S Birkerød, Denmark ASIA Flatirons Solutions (Shanghai) Software Co. Ltd Shanghai, China WP-Understanding Business Rules-LETTER / Flatirons Solutions, Inc. All Rights Reserved