Documentation and Specification

Transcription

1 Document #: D Status: Draft Version 1 Documentation and Specification Process SunSpec Alliance Specification Contributors: Tom Tansy, Tim Keating, Natsuko Gillot, Bob Fox Abstract This document describes the documentation and specification process of SunSpec documents and is a SunSpec Alliance specification draft. Please provide review comments to the authors or at info@sunspec.org Documentation and Specification Process Specification 1

2 Copyright SunSpec Alliance All Rights Reserved. All other copyrights and trademarks are the property of their respective owners. License Agreement and Copyright Notice This document and the information contained herein is provided on an "AS IS" basis and the SunSpec Alliance DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. This document may be used, copied, and furnished to others, without restrictions of any kind, provided that this document itself may not be modified in anyway, except as needed by the SunSpec Technical Committee and as governed by the SunSpec IPR Policy. The complete policy of the SunSpec Alliance can be found at Prepared by the SunSpec Alliance 4030 Moorpark Avenue, Suite 109 San Jose, CA Website: info@sunspec.com Documentation and Specification Process Specification 2

3 Revision History Revision Date Reason Created Documentation and Specification Process Specification 3

4 About the SunSpec Alliance The SunSpec Alliance is a trade alliance of developers, manufacturers, operators and service providers, together pursuing open information standards for the distributed energy industry. SunSpec standards address most operational aspects of PV, storage and other distributed energy power plants on the smart grid including residential, commercial, and utility-scale systems thus reducing cost, promoting innovation, and accelerating industry growth. Over 70 organizations are members of the SunSpec Alliance, including global leaders from Asia, Europe, and North America. Membership is open to corporations, non-profits, and individuals. For more information about the SunSpec Alliance, or to download SunSpec specifications at no charge, please visit About the SunSpec Specification Process SunSpec Alliance specifications are initiated by SunSpec members desiring to establish an industry standard for mutual benefit. Any SunSpec member can propose a technical work item. Given sufficient interest and time to participate, and barring any significant objections, a workgroup is formed and its charter is approved by the board of directors. The workgroup meets regularly to advance the agenda of the team. The output of the workgroup is generally in the form of an Interoperability Specification. These documents are considered to be normative, meaning that there is a matter of conformance required to support interoperability. The revision and associated process of managing these documents is tightly controlled. Other documents are informative, or make some recommendation with regard to best practices, but are not a matter of conformance. Informative documents can be revised more freely and frequently to improve the quality and quantity of information provided. SunSpec Interoperability Specifications follow this lifecycle pattern of DRAFT, TEST, APPROVED and SUPERSEDED. For more information or to download a SunSpec Alliance specification, go to Documentation and Specification Process Specification 4

5 Table of Contents Table of Figures DOCUMENT NAMING CONVENTION Document Classes Document Title Document Reference Number... 7 Document Status Lettering... 7 Document Class Number... 7 Document Number Version Number DOCUMENT ARCHITECTURE Overview Footer Cover Page... 9 Cover Page Elements... 9 Cover Page Format License Agreement and Copyright Notice Page Revision History page About page Table of Contents page Table of Figures (optional) Nomenclature page Document Body Document Body Styles Document Body Numbering Document Body Spacing Appendices References Documentation and Specification Process Specification 5

6 Table of Figures Figure 1: Proper cover page formatting... 9 Figure 2: Revision history table Figure 3: Table of contents example Figure 4: Nomenclature table Figure 5: Proper document body styles Figure 6: Proper document body numbering Figure 7: Proper document body spacing Documentation and Specification Process Specification 6

7 1. DOCUMENT NAMING CONVENTION The document name must follow this specific format: SunSpec [Document Class] [Document Title] [Document Reference Number]-[Version #] For example, by following this format the name of the first draft this document is: SunSpec Specification Documentation and Specification Process D Document Classes The document class falls into one of four categories: Specification Report: a SunSpec commentary on market or technology trend in distributed energy Application note: a description of how to use SunSpec specifications for specific purposes Best practices guide: a description of the process of developing and following SunSpec standards 1.2 Document Title The document title should be recognizable to the workgroup and approved by the SunSpec Board of Directors. It will be indicated on the cover page, in the title area. 1.3 Document Reference Number The document reference number must match the following format: SunSpec [Document Status Letter][Document Class #][Document #]-[Version #] Document Status Lettering The status of each document is to be denoted by the following four letters: D = Draft T = Test A = Approved S = Superseded Document Class Number The class of each document is to be denoted by numbers (1-4), where 1 = Specification 2 = Report 3 = Application note 4 = Best practices guide Documentation and Specification Process Specification 7

8 Document Number The document numbering starts at number For example, the first document in the SunSpec official document library (in chronological order) will be number 2020, the second 2021, the third 2022, etc. The document number is assigned by the SunSpec Alliance operations manager or delegate. 1.4 Version Number The version number will differ depending on the document status. Draft: single digit o E.g., 1, 2, 3, 4, etc. Test: single digit o E.g., 1, 2, 3, 4, etc. Approved: single digit + decimal point o E.g. 1.1, 1.2, 1.3, etc. Superseded by [Current Approved Document] 2. DOCUMENT ARCHITECTURE 2.1 Overview The document is to be organized in the following order; see subsequent sections for more details. A blank document template following the correct formatting is also available as a separate document. 2.3 Cover page 2.4 License agreement and Copyrights notice page 2.5 Revision History page 2.6 About page 2.7 Table of Contents page 2.8 Table of Figures page 2.9 Nomenclature page 2.10 Document body 2.11 Appendices 2.12 References 2.2 Footer Note: no header Left-hand corner: document title Center: page number Right-hand corner: Font (for all 3 elements): Arial, regular, size 10) Documentation and Specification Process Specification 8

9 2.3 Cover Page Cover Page Elements Upper left corner: [Document reference number] (ex: D ) [Status] (Draft, Test, Approved, Superseded) [Version #] (see 1.4 for correct numbering) [Date] (MM-DD-YYYY) [Hit return x 2] [Document Title] SunSpec Alliance [Document Class] [Hit return x 2] Contributors: [Names] [Hit return x 2] SunSpec Logo [Hit return x 4] Abstract [Insert description below] Cover Page Format Element Doc reference number, status, version #, date Format Arial, regular, size 12 Document title Arial, bold, size 26 Document class Arial, regular, size 22 Contributors Arial, regular, size 12 Abstract Figure 1: Proper Cover Page Formatting Arial, regular, size 12, title bolded 2.4 License Agreement and Copyright Notice Page Copyright SunSpec Alliance All Rights Reserved. All other copyrights and trademarks are the property of their respective owners. [Hit return x1] Documentation and Specification Process Specification 9

10 License Agreement and Copyright Notice (Arial, bold, size 18) This document and the information contained herein is provided on an "AS IS" basis and the SunSpec Alliance DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. (Arial, regular, size 12) [Hit return x1] This document may be used, copied, and furnished to others, without restrictions of any kind, provided that this document itself may not be modified in anyway, except as needed by the SunSpec Technical Committee and as governed by the SunSpec IPR Policy. The complete policy of the SunSpec Alliance can be found at (Arial, regular, size 12) [Hit return x2] Prepared by the SunSpec Alliance 4030 Moorpark Avenue, Suite 109 San Jose, CA Website: info@sunspec.org (Arial, regular, size 10) 2.5 Revision History page Title: Revision History (Arial, bold, size 18) Insert the following table: Revision Date Reason MM-DD-YYYY Figure 2: Revision History Table 2.6 About page Title 1: About the SunSpec Alliance (Arial, bold, size 18) [Insert content below, TBD] Title 2: About the SunSpec Specification Process (Arial, bold, size 18) [Insert content below, TBD] 2.7 Table of Contents page Title: Table of Contents The table of contents can only be inserted if each element to be included in the table is formatted with the proper heading. Documentation and Specification Process Specification 10

11 Insert > Index and Tables > Formats > Classic Select Table Change font to Arial Figure 3: Table of Contents Example Table of Figures Nomenclature HEADING Heading 2 8 Heading 3 8 Appendix A 9 Appendix B Table of Figures (optional) Title: Table of Figures A table of figures can only be inserted if a caption is attached to each figure to be included in the table. To attach a caption to a figure: Right-click image Select Insert Caption Type in the proper caption (Style: Times New Roman, bold, size 11, flushed down) To insert the table of figures Insert > Index and Tables > Table of Figures > Format: Simple Select table Change the font to Arial 2.9 Nomenclature page Title: Nomenclature Insert the following table: Abbreviation XXX Figure 4: Nomenclature table Meaning Style: Arial, regular, size 12, column titles bolded Abbreviations are to be organized in chronological order Documentation and Specification Process Specification 11

12 2.10 Document Body Document Body Styles The following styles are to be applied throughout the document body: Heading 1: Arial, bold, size 18, uppercase Heading 2: Arial, bold, size 14 Heading 3 : Arial, bold, size 12 Body text: Times New Roman, regular, size 12 Figure 5: Proper document body styles Note: Every title and graphic is to be flushed to the left throughout the document (1-inch margins) Document Body Numbering Sections are to be organized and numbered in the following fashion: 1. HEADING Heading 2 Heading 3 Figure 6: Proper document body numbering Document Body Spacing Heading 1 o Before: 24pt o After: 6pt Heading 2 o Before: 14pt o After: 6pt Heading 3: o Before: 10pt o After: 6pt Documentation and Specification Process Specification 12

13 Figure 7: Proper document body spacing 1. HEADING 1 [Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vel suscipit ipsum. Donec libero lectus, luctus a ex non, molestie mollis purus. 1.1 Heading 2 Donec posuere tincidunt pharetra. Sed scelerisque consectetur neque, pretium fringilla lacus viverra a. Suspendisse finibus placerat ex, id facilisis nisi. Heading 3 In hac habitasse platea dictumst. Duis quam ante, sollicitudin a quam at, rutrum interdum sapien Appendices Appendices are to be started on a new separate page, following the same formatting as the body of the document References Title: References References are to be listed on a new page in MLA format. Documentation and Specification Process Specification 13