Generic Requirements for Supplier-Provided Documentation

Transcription

1 Generic Requirements for Supplier-Provided Documentation Preface...Preface 1 1. Introduction Purpose Scope Relationship to Other Telcordia Documents Organization of the Document Requirements Terminology Requirement Labeling Conventions Numbering of Requirement and Related Objects Requirement, Conditional Requirement, and Objective Object Identification Beginning Considerations Human Factors Considerations in Documentation Comprehensiveness Comprehensibility Consistency in Format, Terminology, and Numbering General Requirements Determine Functional Category, Subject Area, and Subset Overview of Functional Categories Switching Transport Operations Common/Miscellaneous General Requirements Subject Areas and Subsets Requirements for Developing Documents, by Subject Area General Documentation Subject Area Documentation Guide System Descriptions User Guide Operating Instructions Product Descriptions Feature Description (FD) Documents Hardware Descriptions Software Descriptions Trouble Escalation Procedures v

2 Product Support Descriptions Theory of Operation Power Documentation Subject Area Power Requirements Power System Configuration Descriptions Installation Procedures Routine (Scheduled) Task Procedures Trouble-Locating Procedures System Capacity Subject Area Traffic Capacity Most Limiting Component Call Volume Maximum Busy-Hour Calls Classes of Service Usage-Capacity (CCS) Charts Line Capacity Impact on Traffic Capacities Network Element Interface Subject Area Analog/Digital Interface Description Database Access Procedures Database Maintenance Access Procedures Support System Interface Protocol Details Central Office Cross-Connection Description Office Records Subject Area Office Assignment Documentation Office Options/Features Documentation Trouble Logs Hardware Configuration Records Software Configuration Records Office Parameter Records Translation Records Floor Plans Software and Translations Subject Area Program Specifications Program Maps and Database Layouts Software Trouble Analysis Documentation Software Maintenance Procedures Translations Guides General Requirements for a Translations Guide Line Translations Trunk Translations Routing Translations Billing Translations Other Products and Services Translations Translations Overview Parameters Translations Traffic and Plant Measurements Translations vi

3 Cutover/Bulk Translations Traffic Table Installation and Verification Procedures Patch Administration and Application Procedures Software Release Add/Change Procedures Software/Firmware Source Code Information Office Parameter Add/Change Procedures Office Update/Backup Procedures Planning and Engineering Subject Area Product Technical Specifications Product Planning Guides Building Engineering Documentation Equipment Engineering Documentation Traffic Engineering Documentation Hardware Engineering Documentation Software Engineering Documentation Inventory and Ordering Inventory Details Coding Information Ordering Guide Price and Cost Information Scheduling Information Installation Subject Area New Installation Procedures Cutover Procedures Retrofit Procedures Growth Procedures Hardware/Software Acceptance Test Procedures Provisioning Subject Area Manual Applications Provisioning Guide Database Provisioning Guide General Provisioning Procedures Hardware Provisioning Procedures Software Provisioning Procedures Assignment Provisioning Procedures Maintenance Subject Area Input Message Manuals Output Message Manuals Trouble-Locating/Corrective Action Procedures Maintenance Measurements Documentation Routine (Scheduled) Task Procedures Alarm and Performance Monitoring Procedures Emergency Action and System Recovery Procedures Maintenance Spare Parts Lists Repair and Return Procedures Database Administration Subject Area Traffic Database Administration Procedures Network Traffic Database Management Procedures vii

4 NE System Database Administration Procedures Billing Subject Area Capabilities Description Administration Procedures Automatic Message Accounting (AMA) Procedures Supporting Documentation Description Records Generation Procedures Test Procedures Updating Procedures Reliability and Quality Subject Areas Development and Manufacturing Quality Program Descriptions System Design Reliability and Quality Process Descriptions Software Reliability and Quality Process Descriptions Documentation Quality Control Process Descriptions Product Support and Field Reliability Program Descriptions Prepare Draft Documentation Overview Develop a Plan Determine Delivery Requirements Prepare Documentation Guide Standalone Documents Principles of Effective Writing Verify The Information Verify What Tasks Are Required Verify How Tasks Are Performed Review Technical Details for Accuracy Review Audience and Format Requirements Format and Package the Information Format and Structure Characteristics for Electronic and Paper Documentation Table of Numbering Pages, Captions, and Units of Text Information Changes Other Physical Characteristics Electronic Documentation Functionalities to be Provided Structure, Format, Content, and Tagging Screen Format Type Point Size Illustrations Viewing and Printing Documentation Paper Documentation Size and Arrangement of Type on a Printed Page viii

5 7.3.2 Type Point Size Illustrations Distribute The Documentation Follow-Up Evaluation Overview Check for the Appropriate Level of Detail Update The Documentation When to Use an Addendum When to Use a Revision When to Reissue a Document Appendix A: Documentation Preparation Process for Procedural Documentation... A-1 A.1 An Overview... A-1 A.2 Perform Task Analysis... A-4 A.2.1 Task Definition... A-4 A.2.2 Overview... A-4 A.3 Simplified Procedure... A-4 Appendix B: A Task-Oriented Practice Approach to Preparing Procedural Information... B-1 B.1 What is a Task-Oriented Practice (TOP)?... B-1 B.1.1 Essential Elements of a Task-Oriented Practice (TOP)... B-2 B.1.2 How is a Listing Used in a TOP?... B-2 B.1.3 How are Flowcharts Used in a TOP?... B-4 B.1.4 How are Drawings Used in a TOP?... B-5 B.1.5 How is Text Used in a TOP?... B-8 Appendix C: An Information Mapping Approach to Preparing Procedural Information... C-1 Appendix D: How to Best Present Information... D-1 D.1 Presenting Various Kinds of Information Within Documents... D-1 Appendix E: Network Element Documentation Checklist... E-1 Appendix F: Severity Definitions... F-1 F.1 Introduction... F-1 F.2 Severity Definitions for Switching and Transport Systems... F-1 F.3 Severity Definitions for Operations Systems... F-3 Appendix G: Binding and Packaging Option for Paper Documentation...G-1 G.1 Binding the Documentation... G-1 G.2 Packaging the Documentation: An Overview... G-2 G.3 User-Oriented Documentation Packaging... G-3 References... References-1 Glossary...Glossary-1 ix

6 List of Figures List of Figures Figures Figure 3-1. Relationship between Categories, Subject Areas, and Subsets Figure 5-1. Flow Diagram Showing How to Prepare Draft Documentation Figure A-1. How to Prepare Documentation: Flow Diagram... A-3 Figure A-2. An Example of Task Analysis: Documentation Preparation Procedures and Development Requirements... A-5 Figure B-1. Example of a TOP Listing... B-3 Figure B-2. Example of a TOP Flowchart... B-4 Figure B-3. Example of a TOP Functional Block Diagram... B-6 Figure B-4. Example of a TOP Schematic Diagram... B-7 Figure B-5. Example of TOP Text... B-8 Figure B-6. Example of a TOP Detailed Level Procedure... B-9 Figure C-1. Example of Information Mapping (Procedure Map) Format... C-2 Figure G-1. Documentation Packaging Details... G-2 x

7 List of Tables List of Tables Tables Table 3-1. Subject Areas and Associated Subsets Table 4-1. Subject Area and Subset Documentation Development Requirements Index Table 4-2. Example of Feature Index Table 4-3. CLEI Code Format Table 5-1. Subsets That Must Be Standalone Documents Table An Example of a Document s Change History Section Table A Guide to Selecting an Update Format Table D-1. A Guide to Presenting Information...D-2 Table E-1. Format Matrix for General Documentation... E-1 Table E-2. Format Matrix for Power Documentation... E-2 Table E-3. Format Matrix for System Capacity Documentation... E-3 Table E-4. Format Matrix for Network Element Interface Documentation... E-3 Table E-5. Format Matrix for Office Records... E-4 Table E-6. Format Matrix for Software Documentation... E-5 Table E-7. Format Matrix for Planning and Engineering Documentation... E-6 Table E-8. Format Matrix for Inventory and Ordering Documentation... E-6 Table E-9. Format Matrix for Installation Documentation... E-7 Table E-10. Format Matrix for Provisioning Documentation... E-7 Table E-11. Format Matrix for Maintenance Documentation... E-8 Table E-13. Format Matrix for Billing Documentation... E-9 Table E-12. Format Matrix for Database Administration Documentation... E-9 Table E-14. Format Matrix for Reliability and Quality Documentation... E-10 Table E-15. Subsets That Must Be Standalone Documents... E-11 Table G-1. Matrix for Choosing a Binding for Documentation...G-1 xi