Business Rules in All You Need to Know

Transcription

1 Business Rules in S1000D TM TM All You Need to Know Produced by CDG, A Boeing Company The First Choice in Technical Documentation

2

3 SUMMARY OF CONTENTS Introduction What are S1000D Business Rules? Why Do We Need Business Rules? How to Create S1000D Business Rules What to Document? Categories Layers Timescale Use Comments and Advice Glossary

4 Introduction If you have any connection with the technical documentation industry, especially in the Aerospace and Defense sectors, you will have heard of S1000D. Many companies and organizations are now using S1000D as part of their data management strategy. By using S1000D for the creation and through life management of the technical documentation that supports their equipment, these organizations are beginning to see the efficiency that S1000D can provide. S1000D has developed to be flexible in its application, accommodating the varied requirements of different nations and organizations in both civil and military applications. This increased flexibility has in turn made S1000D more complex; numerous implementation decisions have to be made and disseminated along with guidance on the application across an organization or project. S1000D Business Rules were introduced to help address these challenges. Prior to S1000D issue 2.0, no mention of business rules is made, although business rules are not a new concept in technical documentation. In the past, business rules for creating and managing technical documentation have been around in various forms using a variety of names, such as style guides, chapter plans, author guides, document management plans, publication plans, etc. Business rules were first mentioned in issue 2.0 of S1000D, but it was issue 2.2 before the concept of the Business Rules Exchange file (commonly known the BREX file) was introduced. As its name implies, the BREX was created as a mechanism for exchanging business rules between project partners. It has developed to become not only an exchange file, but also for use by compliance checking tools. This paper will specifically address the purpose, creation, and use of S1000D Business Rules. What are S1000D Business Rules? Wikipedia defines Business Rules as a statement that defines or constrains some aspect of the business. It is intended to assert business structure or to control or influence the behavior of the business. Business rules describe the operations, definitions, and constraints that apply to an organization. Business rules can apply to people, processes, corporate behavior and computing systems in an organization, and are put in place to help the organization achieve its goals. The key point to draw from this definition is that business rules are put in place to help an organization achieve its goals. It therefore follows that each business rule should have a definite and clear purpose. When applied to S1000D, a business rule is a statement that details the result of a decision that impacts any S1000D related activity. Logically any such decision should be made with the aim of ensuring the business achieves its goals. It 4

5 follows that organizations and projects should ensure they clearly understand their goals and required outputs before producing their business rules. Business rules should be driven by the business requirements, and although technical issues may constrain those requirements, the most essential drivers will be the technical, business and market requirements. Why Do We Need Business Rules? Business Rules are needed because S1000D is a complex specification, which is intended to be tailored to meet project specific requirements. The rules are therefore required to avoid different interpretations of the specification, to ensure a common coding and naming strategy, and to ensure interoperability. In addition, S1000D has numerous decision points that require clarification and common interpretation across a project. This means that project participants need to know the specific tailoring and the usage decisions made. It follows that S1000D business rules should be clear, concise, and unambiguous. Remember business rules are written to document the decisions made and to share those decisions with other project participants. Therefore, given the long life-cycle of equipment documented by projects using S1000D, it may be useful to document the rationale behind the decisions made. Doing so will support those decisions and assist present and future project participants in understanding the rationale. Earlier versions of S1000D stated that projects must decide the business rules guidelines. Later versions have broken out most of these decision points under what it calls Business Rules Decision Points, or BRDPs in S1000D jargon. However, there are still many items not included under those BRDPs that require clarification. Therefore in order to avoid expensive rework later in a project, participants need to understand and agree what that specific tailoring will be. In fact S1000D states: Throughout the specification, in particular the authoring chapters, business rule decision points have, wherever possible, been identified. However, in many cases, they have been marked as None identified. Projects and organizations must still decide for themselves whether certain business rules decisions must be made in these cases. How to Create S1000D Business Rules How do we create S1000D business rules and who should be involved in the process then? Business rules creators need go through the specification identifying the decision points specific to the project requirements and make the decision that best meets the project or organization requirements. Software queries can be used to extract that information, or alternatively someone can go through the specification identifying the decision points. Fortunately, S1000D does identify the majority of decision points under the heading of Business Rules, and the task should become easier with the release of issue 4.1 because it will also contain a Business Rules Index. However, with over 750 decision points identified within issue of S1000D, it is not a quick or easy task. In addition, a few software vendors have developed tools that list the decision points, allowing the user to input the decisions made, and based on the input build the BREX file. However, it must be 5

6 remembered that the BREX is not a substitute for the business rules, as currently it does not capture everything. To be effective, the creation task should only be undertaken by personnel who are fully conversant with the S1000D specification, the supporting schemas/dtds, and who fully understand the detail of the technical publications process. Also, if smooth data flow across the enterprise is required, Subject Matter Experts (SMEs) from other areas will have to be involved. System designers, support logisticians, and maintainability engineers input is required. These SMEs have information and knowledge that is vital to the process; task lists, product breakdown structure, maintenance analysis reports all of these contribute to the process. Obviously, the prime contractor and any business partners should be involved as their buy in is needed, plus any contractors, sub-contractors and suppliers who supply their own S1000D data modules. All will need to review and agree to the business rules. What to Document? S1000D gives no guidance on the generation/creation and use of business rules, other than to state they should be created to document the specific tailoring of S1000D for a project or organization. S1000D does provide the guidance in the form of Business Rules Decision Points, or BRDPs, throughout the specification, but does not specify the size, type or quantity of the documents required. Business rules can be created as a single document or as a series of documents covering specific areas, as projects or organizations require. There are various views on what business rules should contain and how much detail should be documented; ultimately the decision on what to document and what to leave out rests with the project. Remember if a topic or subject that requires a rule or guidance is not documented then it is likely to be applied differently by partners, contractors and individuals. Categories Conveniently, S1000D addresses the standardization of business rules generation/creation by introducing the concept of categories. Grouping business rules into categories allows projects and organizations to group the rules by type. Categorizing by type is useful when looking at who should be involved in the creation, development, and review of specific types of rules. The categories defined by S1000D are General, Product Definition, Maintenance, Security, Business Process, Data Creation, Data Exchange, Data Integrity and Management, Legacy Data, and Data Output. General Business Rules General rules cover decisions on items such as which issue of S1000D is to be used, and if the chosen issue is prior to issue 4.0 and after issue 1.9, whether SGML or XML is to be used. They should detail which parts of S1000D will be used (i.e. data module types, DDN, DML, etc.) and include details of any language variants, as well as whether Simplified Technical English will be used. They should also contain general details about the source data to be used, LSA, MSG 3, etc. The rules should detail the rules for data module titles and specific rules for the use 6

7 of cross-references, including any specific wording to be used, as well as whether applicability will be used or not, and if so what type. It is also worth considering detailing who is responsible for specific areas of implementation, such as who is responsible for the creation and management of Terms and Definitions and maintaining any project specific dictionaries. Product Definition Rules As the title implies, these rules cover how the data modules and resulting technical publications will be structured in relation to the product definition. As a minimum, these rules should document Model Identification codes, System Difference Codes, the Data Module coding strategy, and the Standard Numbering System (SNS) structure. Choose the SNS for the project from chapter 8 of S1000D, and document the choice, including any modifications to that SNS. Alternatively, create a project SNS and document it. The BREX files supporting recent issues of S1000D include a mechanism for exchange of the SNS. The data module coding strategy should detail the breakdown of the data modules in relation to either the physical or functional breakdown of the product being documented. The SNS structure should be developed in conjunction with the product breakdown as defined by either engineering or design. If using S2000M or logistic support analysis, the SNS should be developed in conjunction with these disciplines. Define the applicability rules, the values for type, model, version, and other values. Given the major changes to Applicability over the past few issues of S1000D, this will be very much dependent on the issue of S1000D used. Define how applicability will be managed. Do not underestimate the size of this task and the effort required. Maintenance Philosophy Rules Maintenance philosophy rules should cover the types of data modules that will be written, the depth and scope of the information to be delivered, all in line with the maintenance levels. They should include the use of the information sets, a list of information codes, information code variants, and information names to be used in the project, including the use of not given codes. If extended information names are required, they should be documented in these rules. Detail the item location codes that are to be used; do not confuse these with level of repair. Where LSA is used, consider a map between information codes and LSA task codes. Remember if a project creates new information codes it must do so in accordance with Chapters 1.3 and 8.4 of S1000D; failure to do so may cause complications further into the project life, should a code conflict with future S1000D allocation of information codes. Security Rules These rules cover the definitions of security classifications and their use. They also include copyright (including any associated markings and statements) national security restrictions, project specific security instructions and any other business restrictions. They should also specify any authoring access details for the various classes of data modules, including sub-contractor access, as well as disposal instructions. It is important to make sure that what is detailed in these rules is compliant with national, organizational and company security requirements, as well as addressing any project-specific requirements. Remember there may be restrictions on who can author, view, or modify data. In multiple partner projects, you should also write the rules for which partners are responsible for what product hardware, in terms of who can author, modify, or amend content. Business Process Rules Business process rules define how S1000D data modules are created in line with other related business processes. 7

8 These are often internal to an organization and may form part of departmental operating procedures. If so, refer out to those procedures, and make sure they are available to all concerned. These rules can also cover external processes such as input and output definitions for interchange with other disciplines. Cover any integration methods with external systems such as provisioning and logistic support analysis records. Detail how the one to one relationship between data modules and the tasks identified by the logistic support analysis is maintained. These rules should also cover workflow procedures, including the workflow between partners and customers. The rules will also cover the relationship between data module codes, publication module codes and the learning content in any training data modules. The rules should cover both internal and external Quality Assurance (QA) details. Any QA rules should reference out to the relevant quality plan and manual; cover the use of any national, organization or project specific QA rules. They should also cover the use of any parsing and checking tools, Simplified English Checkers, and may include links to assist in validation/verification. They should include any checks to ensure compliance with the SNS and data module coding strategy. These rules should define what should be checked and can also be used to provide a checklist for use by project participants. Data Creation Rules Data creation rules cover the creation of textual data, graphics, 3D content and multimedia objects. Rules for textual data cover both writing and mark-up, and they include language, abbreviations, the use of acronyms, and how numeric values are to be included. They also include the use of units of measure, terminology, dictionaries, punctuation, the use of capitals, as well as the rules for warnings and cautions. These are the rules that are often referred to as the author s style guide. They should define which elements are mandated and which are not allowed; many of these rules are context dependent. Where appropriate these rules should also cover the definition of the content of elements and attributes. They should also include the fixed attribute values as well as the project configurable attribute values. Rules for graphics, 3D content and multimedia objects that are non-textual data should include the ICN format, allowable file types/formats, illustration security, partner codes within the ICN, etc. They should include the rules for the use of hotspots within graphics and the use of parameter within multimedia. They should cover such items as line weights, fonts and font sizes within illustrations, the use of symbols and colors, as well as when to use line art, photographs, 3D models, audio, etc. They should also cover the use of ICN within the illustration area, noting whether the ICN should be displayed or not. If multimedia is to be used they should define the allowable formats and any specific viewer requirements. Clearly the viewer or plug-in for multimedia is directly related to the formats selected and any rules and/or limitations should be listed in this section. The Rules should also detail how text will be handled within a multimedia scene. Data Exchange Rules Data exchange rules should cover how data is exchanged between partners and customers, The rules should define the data exchange methods, that is the rules for the use of the DDN, DMRL, DML and CSL along with any specific rules pertaining to the file based transfer protocol. These rules should also cover the frequency of exchange along with acceptance and rejection criteria. Data Integrity Rules Data integrity rules should cover how data is managed and archived within the CSDB (Common Source DataBase) environment. They should include how data is managed in a multi-partner/contractor environment. Rules to cover the project prime contractor and customer relationship are a good idea, as is detailing how these are connected to workflow within the CSDB management system. These rules should detail who (if anyone) holds copies of the CSDB and how these copies are synchronised, as well as who verifies the systems and the management of that verification process. This section should also document what happens when one partner accepts a data module and another partner or the customer rejects that same data module. The section should also cover the rules for dealing with non-compliant data. 8

9 Legacy Data Rules For those projects that have existing legacy data in other formats or other issues of S1000D, then legacy data rules will be required. Legacy data business rules are a topic in their own right. Suffice it to say that it is wise to document any pre-conversion tasks, rules for illustration conversion or use, how to map chapters, work packages, etc. to data module codes and any rules for the verification of post conversion data if that is deemed necessary. In addition, and dependent on the format of the legacy data, it may be possible to document the mapping between legacy and S1000D elements and attributes. Data Output Rules Data output rules are concerned with how the data is presented and with the display methods the project will use. These rules are directly related to the rules on text, graphics and multimedia creation. These rules are also affected by the functionality matrix and how it is completed. They cover the data output formats, such as paper or page oriented and IETP/IETM formats, as well as multimedia and SCORM output. They should also cover such items as display font sizes, how some elements and attributes are displayed, and the use of stylesheets. Layers S1000D issue 4.0 introduces the concept of layering of business rules. This allows national institutions, organizations, and projects to create a hierarchical structure of rules. A nation or organization can write rules that tailor S1000D to meet its requirements while allowing projects to tailor S1000D further, while staying within the rules of the parent nation or organization. Layering means that each level of organization can write its own business rules and impose them on organizations lower down the hierarchy. S1000D states: A business rules layer indicates the level of stakeholders within the hierarchy to which the business rules apply. To clarify, Business Rules can be written by an organization, as well as by a project team; they may conflict and therefore need to be arranged in a hierarchy. Nations and organizations should choose an appropriate hierarchy based on their needs. 9

10 This actually means that Organizations, or Departments of Defense, or Services such as the Army, Navy, or Air Force can write their rules to constrain projects and ensure their business requirements are met (see Figure 1). This hierarchy allows projects to define their own rules within the limits of the organization or service rules, with each layer of rules limiting the subordinate ones. An example of this is that a defense organization would write rules that covered all three services, to which those three services would need to agree. Each service could then write its own rules while ensuring those rules met the broader defense organizations rules as established by all three groups. How does all this affect the creation of rules? Clearly there is a need to know the rules from organizations to which the project or organization is subordinate. If the rules from a higher level organization do not meet a project or organizations requirements then there is a need to negotiate with the higher level organization. In addition, it would not be wise or cost effective to write the same rules again if they already meet the project requirements. However S1000D does not adequately address what happens when there are two higher level organizations with different rules as customers of the same project. For example, an engine could be used in an aircraft and used to power a ship what then? Obviously, there should be some negotiations or else there could be expensive rework to meet customer requirements. Generic National National Organization Project Project Supplier Figure 1 - Rules Constraint Supplier Project Organization Timescale When should business rules be started? Business rules are the first step in the S1000D process. The best advice is to create them before data module production begins. However practicalities mean production will probably begin before the rules are completed; therefore projects should prioritize the rules development, dealing with the most critical items first. Make a plan and gain approval from all participants. It can take a long time to reach consensus, so make sure your expectations on this approval process are realistic. National Generic S1000D Figure 2 - Hierarchy of Rules Before a project can start to produce business rules, it is necessary to know the issue of S1000D that will be used, the maintenance policy and product structure, any project specific requirements and the delivery method. S1000D provides an example plan of a sequence of business rules production relative to categories. This is only a guide and caution on planning is advised, as gaining agreement on the rules can be time consuming. Use Once written, the rules must be implemented and policed, but that only works if the rules are realistic and useable. Good business rules are imperative to the success of the project, so it is worthwhile ensuring they work. Run test 10

11 batches to check the rules. Acceptance and rejection criteria should be clearly defined and applied. Projects fail not only because of the lack of a coherent set of business rules, but also because good rules were not applied and policed. Be sure to detail who will be responsible for ensuring compliance and what the remedial action should be if data fails. Wherever possible use checkers to ensure compliance; it is also advisable to build rules compliance into the QA system. Comments and Advice Business rules are required to clarify the organizational and project specific tailoring of S1000D. The creation of the rules is a complex task, one that should only be undertaken by personnel who are familiar with both the S1000D specification and the technical documentation process, including both creation and through life management. The rules are required to detail the project specific tailoring of S1000D; they are intended to explain that tailoring to all project participants in order to avoid different interpretations of the specification. The creation process requires organization and planning, and the rules only work if there is buy-in from all project participants. It is important to recognize that those writing the rules fully understand both S1000D and the project or organization requirements. Once the rules have been written, they should be reviewed to ensure they are correct and usable, and that they will enable the production of data that meets the project requirements. There are many review methods available and projects should choose the method most appropriate to their needs. It is suggested that rules be reviewed in the context in which it was intended to be applied. The reviewing process should be relevant and inclusive, include authors and customers, and where practical use collaborative tools. Projects will probably require several review cycles, a phased review, and approval process; this will deliver rules that are more robust. Once review is complete, use test data to check the rules and the output. Finally don t be surprised if the rules have to be modified in the light of production experience. Something will always be missed or some requirement will change, but robust well developed rules created at the start of a project can prevent expensive rework later. 11

12 GLOSSARY BREX BRDP s SNS CSDB LSA Business Rules Exchange File Business Rules Decision Points Standard Numbering System Common Source DataBase Logistic Support Analysis 12

13 About the Author Ian Proctor is a Technical Publications Consultant for CDG. Ian provides S1000D consultancy services to support CDG customers worldwide. He has been involved in technical publishing for 19 years. Working with S1000D for the last 10 years, Ian possesses a high level of knowledge and experience related to S1000D. He has overseen the production of data modules for numerous S1000D projects, including for a large, multi-division equipment manufacturing corporation to support multi-variant equipment models. Ian is an active member of the S1000D Electronic Publications Working Group, Chairperson for the Multimedia Task Team and actively contributes to the UK S1000D Working Group. 13

14 About CDG CDG, a Boeing Company, specializes in helping organizations maximize their operations efficiency with engineering lifecycle services and software solutions. CDG Services and Solutions include: 4 Technical Documentation Services & Solutions m Technical Authoring of ATA and S1000D Technical Publications n Maintenance Manuals, Illustrated Parts Catalogs, Customer-Originated Changes (COCs), Service Bulletins, Structural Repair Manuals, Wiring Diagrams, T-Files m Interactive Electronic Technical Manual (IETM and IETP) Authoring and Software Solutions m S1000D Training and Consulting m Content Conversion Services Including paper or microfilm to digital delivery 4 Training Solutions m elearning Content Development (ATA 104 Level 1 to 3) m Mobile Device Access for On-Demand elearning m Computer-Based Training (CBT) m Instructor-Led Training (ILT) m Learning Management Systems (LMS) 4 Software Solutions m Smart IPC An Interactive Parts Catalog capable of delivering multiple OEM data in a single platform, all seamlessly integrated with parts inventory ERP systems and external parts sourcing databases and websites. Smart IPC can also be accessed via mobile devices such as cell phones and tablet computers for quick, portable access to technical information and parts data anytime, anywhere. m Wiring Illuminator Web Advanced Interactive Wiring Troubleshooting Tool m Supply Chain Analytics Software solutions providing decision support related to Parts & Maintenance Operations 4 Engineering Services m Engineering Design Services m Aircraft Reconfiguration/Mods m Stress Analysis m CAD Conversions m CATIA, ENOVIA, DELMIA Expertise For more than 40 years, CDG has provided mission-critical services and solutions to support the aerospace and defense industry. Our employees are constantly integrating new ideas into our processes, striving for higher quality standards, higher speed, and lower cost solutions for our customers. With more than 1,200 employees worldwide, CDG production and customer service facilities are located in multiple locations throughout the US, Europe, and India. Visit for more information.

15

16 The Americas Europe India Corporate Headquarters 4060 N. Lakewood Blvd Building 801, 5th Floor Cypress, CA USA Toll Free: (800) Phone: (714) Gate House Fretherne Road Welwyn Garden City Hertfordshire AL8 6NS UK Phone: +44 (0) Continental DataGraphics Technical Services India Pvt Ltd a Boeing Company Building #99-B37 Block 9A, 3rd Floor, DLF IT Park SEZ 1/124 Shivaji Gardens, Mount Poonamalle Road Manapakkam, Chennai INDIA Phone: BUSRULES1000DWP A