David A. Flynn

TM Version X.Y Document Format & Style Guide Version 1.0 David A. Flynn Feb 01, 2021 Copyright Information Copyright © 2021 All Rights Reserved This publication is protected by federal copyright law. No part of this publication may be copied or distributed, stored in a retrieval system, or translated into any human or computer language in any form or by any means, electronic, mechanical, magnetic, manual or otherwise, or disclosed to third parties without the express written permission of . makes no representation or warranties with respect to the contents hereof and specifically disclaim any implied warranties of merchantability or fitness for a particular purpose. Further, reserves the right to revise this publication and to make changes from time to time in the contents hereof without obligation of to notify any person or organization of such revision or changes. has prepared this guide for use by personnel and authorized third parties as a guide to proper operation and/or maintenance of equipment and software. The drawings and specifications contained herein are the property of . Trademarked names may appear throughout this document. Rather than list the names and entities that own the trademarks or insert a trademark symbol with each mention of the trademarked name, the names are used only for editorial purposes and to the benefit of the trademark owner with no intention of infringing upon that trademark. Address comments and corrections to: TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | i Revision History Revision History DATE RELEASE REVISION DESCRIPTION July 22, 2020 0.1 Initial draft David A. Flynn Feb 01, 2021 1.0 First base lined document David A. Flynn TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved MODIFIED BY Internal Page | ii About this Document About this Document This section briefly describes key details of this document – Purpose of this Document The purpose of this document is to list and describe the tenets of technical user documentation applicable in the design, development, documentation, and review of user manuals of TM. Scope of this Document The section describes the topics in and out of scope of this document – In Scope The scope of this document includes –  the defined standards, their implementation, and their review for the user documentation of TM,  the content management strategy implemented for the user documentation of TM, and  the configuration management strategy implemented for the user documentation of TM. Out of Scope The scope of this document does not include –     the technical specifications of TM, the project management strategy utilized, the risk management strategy implemented, the configuration management strategy implemented for the development of the code of TM,  the quality checking strategy and plan of TM, and  the change management strategy of TM. Intended Audience of this Document The intended audiences of this document are –     technical authors of the user documentation of TM, our clients, and personnel, groups, or associations as designated by our clients, the change control board of TM, and the product development team of TM. TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | iii About this Document Typographical Conventions / Customaries used in this Document The customaries used in this document include the following –  Note: The purpose of this customary is to provide important information corresponding to an already stated fact. A note is depicted in the following manner in this document – Note: This is we depict a note in this document. In case the note text is long enough to span to two lines or more, we need to ensure that the left indentation of such a note is the same as that of the preceding paragraph.  Tip: The purpose of this customary is to provide additional information supplementing an already stated fact. A tip is depicted in the following manner in this document – Tip This is how we depict a tip in this document. In case the tip text is long enough to span to two lines or more, we need to ensure that the left indentation of such a tip is the same as that of the preceding paragraph.  Warning: The purpose of this customary is to provide critical information corresponding to an already stated fact. A warning is depicted in the following manner in this document – Warning: This is how we depict a warning in this document. In case the warning text is long enough to span to two lines or more, we need to ensure that the left indentation of such a warning is the same as that of the preceding paragraph.  Reference: The purpose of this customary is to refer the user to another section in this document or another document or to an external reference. A reference is depicted in the following manner in this document – Reference: This is how we depict a reference in this document. In case the reference text is long enough to span to two lines or more, we need to ensure that the left indentation of such a warning is the same as that of the preceding paragraph. TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | iv About this Document Abbreviations / Acronyms used in this Document The table below describes the abbreviations / acronyms used in this document – Table 1: Abbreviations / acronyms used in this document ABBREVIATION CCB DESCRIPTION Change Control Board GUI, UI Graphical User Interface, User Interface HTML Hyper Text Markup Language MSMQ Microsoft Messaging Queue MSSQL Microsoft Structured Query Language PDF Portable Document Format PDR Pervasive Data Replication RAFT Retail Application Framework Technology SME Subject Matter Expert TOC, TOT, TOF WYSIWYG Table of Contents, Table of Tables, Table of Figures What-You-See-Is-What-You-Get Organization of this Document This document contains the following chapters and appendices – Table 2: Organization of this document CHAPTER DESCRIPTION Chapter 1 An Introduction to this Guide Chapter 2 Segregation of the Product Suite Chapter 3 Usage of Fields Chapter 4 Structure of a Typical User Manual Chapter 5 Utilized MS Word Styles & their Composition Chapter 6 Adopted Writing Style Chapter 7 Content Management Strategy Chapter 8 Configuration Management Strategy Appendix A Sample Defect Log Appendix B Extracting Comments From An Ms Word File Using A Macro Appendix C Master Document Template Appendix D Sub Document Template TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | v About this Document TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | vi Table of Contents Table of Contents ABOUT THIS DOCUMENT ...................................................................................................................................... III PURPOSE OF THIS DOCUMENT ......................................................................................................................................... III SCOPE OF THIS DOCUMENT ............................................................................................................................................. III In Scope ............................................................................................................................................................... iii Out of Scope ........................................................................................................................................................ iii INTENDED AUDIENCE OF THIS DOCUMENT ......................................................................................................................... III TYPOGRAPHICAL CONVENTIONS / CUSTOMARIES USED IN THIS DOCUMENT .............................................................................. IV ABBREVIATIONS / ACRONYMS USED IN THIS DOCUMENT........................................................................................................ V ORGANIZATION OF THIS DOCUMENT .................................................................................................................................. V CHAPTER - 1. AN INTRODUCTION TO THIS GUIDE .......................................................................................... 11 CHAPTER - 2. SEGREGATION OF THE PRODUCT SUITE .................................. ERROR! BOOKMARK NOT DEFINED. 2.1 PRODUCT BRANDING .............................................................................................. ERROR! BOOKMARK NOT DEFINED. 2.2 TM PRODUCT SUITE STRUCTURE .......................................................... ERROR! BOOKMARK NOT DEFINED. 2.3 GRAPHICAL USER INTERFACE (GUI) ELEMENTS AND THEIR REFERENCE PRONOUNS ............. ERROR! BOOKMARK NOT DEFINED. CHAPTER - 3. USAGE OF FIELDS .................................................................... ERROR! BOOKMARK NOT DEFINED. CHAPTER - 4. STRUCTURE OF A TYPICAL USER MANUAL .............................. ERROR! BOOKMARK NOT DEFINED. 4.1 COVER SHEET ........................................................................................................ ERROR! BOOKMARK NOT DEFINED. 4.2 COPYRIGHT INFORMATION ....................................................................................... ERROR! BOOKMARK NOT DEFINED. 4.3 REVISION HISTORY.................................................................................................. ERROR! BOOKMARK NOT DEFINED. 4.4 ABOUT THIS DOCUMENT .......................................................................................... ERROR! BOOKMARK NOT DEFINED. 4.4.1 Purpose of this document ....................................................................... Error! Bookmark not defined. 4.4.2 Scope of this document ........................................................................... Error! Bookmark not defined. 4.4.2.1 In scope .......................................................................................................... Error! Bookmark not defined. 4.4.2.2 Out of Scope .................................................................................................. Error! Bookmark not defined. 4.4.3 Intended Audience .................................................................................. Error! Bookmark not defined. 4.4.4 Typographical Conventions / Customaries used in this document ......... Error! Bookmark not defined. 4.4.4.1 Note ............................................................................................................... Error! Bookmark not defined. 4.4.4.2 Tip .................................................................................................................. Error! Bookmark not defined. 4.4.4.3 Warning ......................................................................................................... Error! Bookmark not defined. 4.4.4.4 Reference ....................................................................................................... Error! Bookmark not defined. 4.4.5 Abbreviations / Acronyms used in this document ................................... Error! Bookmark not defined. 4.4.6 Organization of this document ............................................................... Error! Bookmark not defined. 4.5 AUTO-GENERATED TABLES OF A DOCUMENT ............................................................... ERROR! BOOKMARK NOT DEFINED. TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | 7 Table of Contents 4.5.1 Table of Contents .................................................................................... Error! Bookmark not defined. 4.5.1.1 Key Points to Note While Generating a TOC .................................................. Error! Bookmark not defined. 4.5.1.2 Generating a TOC in MS Word ....................................................................... Error! Bookmark not defined. 4.5.2 Table of Figures ....................................................................................... Error! Bookmark not defined. 4.5.2.1 Key Points to Note While Generating a TOF .................................................. Error! Bookmark not defined. 4.5.2.2 Generating a TOF in MS Word ....................................................................... Error! Bookmark not defined. 4.5.3 Table of Tables ........................................................................................ Error! Bookmark not defined. 4.5.3.1 Key Points to Note While Generating a TOT .................................................. Error! Bookmark not defined. 4.5.3.2 Generating a TOT in MS Word ....................................................................... Error! Bookmark not defined. 4.6 DOCUMENT HEADER ............................................................................................... ERROR! BOOKMARK NOT DEFINED. 4.7 DOCUMENT FOOTER ............................................................................................... ERROR! BOOKMARK NOT DEFINED. 4.8 BODY CONTENT OF THE USER MANUAL ...................................................................... ERROR! BOOKMARK NOT DEFINED. 4.8.1 Introduction to the Suite / Application.................................................... Error! Bookmark not defined. 4.8.2 Getting Started ....................................................................................... Error! Bookmark not defined. 4.8.3 Module Description Sections ................................................................... Error! Bookmark not defined. 4.9 APPENDICES – FAQS / AUXILIARY INFORMATION / SAMPLES .......................................... ERROR! BOOKMARK NOT DEFINED. 4.10 INDEX .............................................................................................................. ERROR! BOOKMARK NOT DEFINED. 4.10.1 Key Points to Note While Generating an Index .................................. Error! Bookmark not defined. 4.10.2 Marking Index Entries ........................................................................ Error! Bookmark not defined. 4.10.3 Generating the Index.......................................................................... Error! Bookmark not defined. CHAPTER - 5. UTILIZED MS WORD STYLES & THEIR COMPOSITION .............. ERROR! BOOKMARK NOT DEFINED. 5.1 COVER SHEET FORMATTING ..................................................................................... ERROR! BOOKMARK NOT DEFINED. 5.2 REVISION HISTORY FORMATTING ............................................................................... ERROR! BOOKMARK NOT DEFINED. 5.3 PREFACE FORMATTING STYLES & THEIR COMPOSITION .................................................. ERROR! BOOKMARK NOT DEFINED. 5.4 BODY CONTENT TEXT FORMATTING ........................................................................... ERROR! BOOKMARK NOT DEFINED. 5.5 COMPOSITION OF HEADINGS .................................................................................... ERROR! BOOKMARK NOT DEFINED. 5.6 LISTS AND THEIR FORMATTING COMPOSITION .............................................................. ERROR! BOOKMARK NOT DEFINED. 5.6.1 Unordered List ......................................................................................... Error! Bookmark not defined. 5.6.2 Ordered List ............................................................................................. Error! Bookmark not defined. 5.7 TABLES ................................................................................................................. ERROR! BOOKMARK NOT DEFINED. 5.8 FIGURES ............................................................................................................... ERROR! BOOKMARK NOT DEFINED. 5.9 CROSS REFERENCES & HYPERLINKS ............................................................................ ERROR! BOOKMARK NOT DEFINED. CHAPTER - 6. ADOPTED WRITING STYLE ...................................................... ERROR! BOOKMARK NOT DEFINED. 6.1 GENERIC POINTS .................................................................................................... ERROR! BOOKMARK NOT DEFINED. 6.2 SPELLING, GRAMMAR, AND READABILITY STATISTICS ..................................................... ERROR! BOOKMARK NOT DEFINED. 6.3 WORD USAGE ....................................................................................................... ERROR! BOOKMARK NOT DEFINED. TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | 8 Table of Contents 6.4 ACTIONS ............................................................................................................... ERROR! BOOKMARK NOT DEFINED. 6.5 STRUCTURE OF THE MODULE DESCRIPTION SECTIONS.................................................... ERROR! BOOKMARK NOT DEFINED. 6.6 ILLUSTRATIONS & THEIR PRESENTATION ...................................................................... ERROR! BOOKMARK NOT DEFINED. CHAPTER - 7. CONTENT MANAGEMENT STRATEGY ...................................... ERROR! BOOKMARK NOT DEFINED. 7.1 MASTER DOCUMENT FEATURE OF MS WORD ............................................................. ERROR! BOOKMARK NOT DEFINED. 7.2 DEFECT IDENTIFICATION & REMOVAL PROCESS ............................................................ ERROR! BOOKMARK NOT DEFINED. 7.2.1 Defect Identification ............................................................................... Error! Bookmark not defined. 7.2.2 Defect Removal ....................................................................................... Error! Bookmark not defined. CHAPTER - 8. CONFIGURATION MANAGEMENT STRATEGY .......................... ERROR! BOOKMARK NOT DEFINED. APPENDIX - A. SAMPLE DEFECT LOG .............................................................. ERROR! BOOKMARK NOT DEFINED. APPENDIX - B. DEFINED. EXTRACTING COMMENTS FROM AN MS WORD FILE USING A MACRO .. ERROR! BOOKMARK NOT APPENDIX - C. MASTER DOCUMENT TEMPLATE ............................................ ERROR! BOOKMARK NOT DEFINED. APPENDIX - D. SUB DOCUMENT TEMPLATE ................................................... ERROR! BOOKMARK NOT DEFINED. INDEX .................................................................................................................................................................. 12 TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | 9 Table of Figures Table of Figures FIGURE 1: A SAMPLE COVER SHEET........................................................................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 2: INDEX AND TABLES POPUP WINDOW .......................................................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 3: TABLE OF CONTENTS TAB ......................................................................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 4: CONFIRMATION DIALOG BOX TO REPLACE AN EXISTING TOC ........................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 5: INDEX AND TABLES POPUP WINDOW .......................................................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 6: TABLE OF FIGURES TAB ............................................................................................ ERROR! BOOKMARK NOT DEFINED. FIGURE 7: CONFIRMATION DIALOG BOX TO REPLACE AN EXISTING TOF............................................ ERROR! BOOKMARK NOT DEFINED. FIGURE 8: INDEX AND TABLES POPUP WINDOW .......................................................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 9: TABLE OF FIGURES TAB ............................................................................................ ERROR! BOOKMARK NOT DEFINED. FIGURE 10: TABLE OF TABLES TAB ........................................................................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 11: CONFIRMATION DIALOG BOX TO REPLACE AN EXISTING TOF.......................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 12: INDEX AND TABLES POPUP WINDOW ........................................................................ ERROR! BOOKMARK NOT DEFINED. FIGURE 13: MARK INDEX ENTRY POPUP .................................................................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 14: MARK INDEX ENTRY POPUP .................................................................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 15: INDEX AND TABLES POPUP WINDOW ........................................................................ ERROR! BOOKMARK NOT DEFINED. FIGURE 16: CONFIRMATION DIALOG BOX TO REPLACE THE EXISTING INDEX ....................................... ERROR! BOOKMARK NOT DEFINED. FIGURE 17: READABILITY STATISTICS OF THIS DOCUMENT ............................................................. ERROR! BOOKMARK NOT DEFINED. Table of Tables TABLE 1: ABBREVIATIONS / ACRONYMS USED IN THIS DOCUMENT ................................................................................................ V TABLE 2: ORGANIZATION OF THIS DOCUMENT .......................................................................................................................... V TABLE 3: ELEMENTS OF THE COVER SHEET................................................................................. ERROR! BOOKMARK NOT DEFINED. TABLE 4: FONTS USED ON THE COVER SHEET WITH THEIR SIZES ..................................................... ERROR! BOOKMARK NOT DEFINED. TABLE 5: PREFACE FORMATTING STYLES & THEIR COMPOSITION..................................................... ERROR! BOOKMARK NOT DEFINED. TABLE 6: COMPOSITION OF HEADINGS ..................................................................................... ERROR! BOOKMARK NOT DEFINED. TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | 10 Error! No text of specified style in document. Chapter - 1. AN INTRODUCTION TO THIS GUIDE TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | 11 Index Index < G TM Product Suite Structure ...............12 Generating a TOF in MS Word .................................26 A Generating a TOT in MS Word .................................30 Abbreviations / Acronyms used in this document...21 Generating the Index ...............................................40 About this document ...............................................19 Generic Points..........................................................47 Actions .....................................................................49 Getting Started ........................................................34 Adopted Writing Style .............................................47 GUI Elements and their Reference Pronouns ..........13 An Introduction to this Guide ..................................10 I Auto-generated Tables of a Document ...................21 Illustration & their Presentation ..............................51 B In scope....................................................................19 Body Content of the User Manual ...........................34 Index ........................................................................37 Intended Audience ..................................................19 C Composition of Headings.........................................44 Configuration Management Strategy ......................54 Introduction to the Suite / Application ....................34 K Content Management Strategy ...............................52 Key Points to Note While Generating a TOC ...........22 Copyright Information .............................................17 Key Points to Note While Generating a TOF ............26 Cover Sheet..............................................................16 Key Points to Note While Generating a TOT ............29 Cover Sheet Formatting ...........................................42 L Cross References & Hyperlinks ................................46 Lists ..........................................................................44 D M Defect Identification ................................................53 Marking Index Entries ..............................................38 Defect Removal .......................................................53 Master Document Feature of MS Word ..................52 Document Footer.....................................................33 Master Document Template ...................................60 Document Header ...................................................33 Module Description Sections ...................................35 E O Extracting Comments From An Ms Word File Using A Macro ..................................................................56 Ordered List .............................................................45 F Out of Scope ............................................................19 Organization of this document ................................21 Figures .....................................................................46 TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | 12 Index P T Preface Formatting Styles & their Composition ......43 Table of Contents ....................................................22 Product Branding .....................................................11 Table of Figures .......................................................26 Purpose of this document .......................................19 Table of Tables .........................................................29 R Tables .......................................................................45 Revision History .......................................................18 Revision History Formatting ....................................42 S The Defect Identification & Removal Process .........53 Typographical Conventions / Customaries used in this document .....................................................20 U Sample Defect Log ...................................................55 Scope of this document ...........................................19 Segregation of the Product Suite .............................11 Spelling, Grammar, and Readability Statistics .........47 Structure of a Typical User Manual .........................15 Structure of the Module Description Sections ........49 Unordered List .........................................................44 Usage of Fields .........................................................14 Utilized MS Word styles & their Composition .........42 W Word Usage .............................................................48 Sub Document Template .........................................61 TM Version X.Y Document Format & Style Guide Version 1.0 PI - DFSG - 1.0 Copyright © 2021. All Rights Reserved Internal Page | 13