Appendix C. Documentation Specifics[LINK]
Documents that module developers will typically be updating or changing are the: Input Output Reference, Engineering Documentation, and Output Details and Examples. You may, of course, note revisions to other documents.
All of the EnergyPlus documentation follows a Word™ template – report.dot.
This template takes care of many of the nuances of formatting so that the documents all retain the same “look and feel”. The template itself will contain examples for the IORef and Engineering Documentation.
General guidelines:
Don’t get fancy with formatting. No extra “enters” are needed to space the paragraphs.
Submit your pictures as pictures (jpeg, tif, gif). This will allow you to “insert captions” below them and have them automatically numbered. (This also allows them to be re-numbered once inside the EnergyPlus documents). Don’t use Text boxes.
Likewise, use an “insert caption” on tables.
Table captions go above the table. Figure captions go below.
If you want to reference a table or figure in your text, use “insert cross reference” and select table or figure as appropriate. Usually, just use the “label and number” option.
Body Text is the expected style for most text. DO NOT put object names in a different font (such as Courier) or as a different size though you may bold them for emphasis.
Headings are used judiciously to help separate text.
Object names (IOReference) are Heading 3.
Each field must be described and shown as Heading 4 followed by the description. Form should be “Field: <field Name>”. (Exception: if your object has a repeating set of fields – you may describe the initial field set in detail such as is done for the branch specifications fields in the Branch object).
Each object’s IDD must be shown and use the format “IDD Definition”.
An excerpt IDF using the object must be shown.
Output variables for the object must be shown (heading 4) with a heading 3 <object name> Output variables preceding.
Equations may be inserted using the Microsoft™ Equation Editor. Internally we use software called “MathType” – that also may be used for Equations. It is not desirable to number every equation. If you want to reference the equations, of course, you will need to number them – it is best to number them in plain text and then we can edit them into the rest of the documents.
Each Engineering Reference section should contain a “References” section and should be formatted in author style (not numbered).
Example References:
ASHRAE. 1993. 1993 ASHRAE Handbook – Fundamentals. Atlanta: American Society of Heating, Refrigerating, and Air-Conditioning Engineers, Inc.
Chapman, A. J. 1984. Heat Transfer, 4th Edition, New York: Macmillan Publishing Company.
Lienhard, J. H. 1981. A Heat Transfer Textbook, Englewood Cliffs, N.J.: Prentice-Hall, Inc.
McClellan, T. M., and C. O. Pedersen. 1997. Investigation of Outside Heat Balance Models for Use in a Heat Balance Cooling Load Calculation. ASHRAE Transactions, Vol. 103, Part 2, pp. 469-484.
Walton, G. N. 1983. Thermal Analysis Research Program Reference Manual. NBSSIR 83-2655. National Bureau of Standards.
Appendix C. Documentation Specifics[LINK]
Documents that module developers will typically be updating or changing are the: Input Output Reference, Engineering Documentation, and Output Details and Examples. You may, of course, note revisions to other documents.
All of the EnergyPlus documentation follows a Word™ template – report.dot.
This template takes care of many of the nuances of formatting so that the documents all retain the same “look and feel”. The template itself will contain examples for the IORef and Engineering Documentation.
General guidelines:
Don’t get fancy with formatting. No extra “enters” are needed to space the paragraphs.
Submit your pictures as pictures (jpeg, tif, gif). This will allow you to “insert captions” below them and have them automatically numbered. (This also allows them to be re-numbered once inside the EnergyPlus documents). Don’t use Text boxes.
Likewise, use an “insert caption” on tables.
Table captions go above the table. Figure captions go below.
If you want to reference a table or figure in your text, use “insert cross reference” and select table or figure as appropriate. Usually, just use the “label and number” option.
Body Text is the expected style for most text. DO NOT put object names in a different font (such as Courier) or as a different size though you may bold them for emphasis.
Headings are used judiciously to help separate text.
Object names (IOReference) are Heading 3.
Each field must be described and shown as Heading 4 followed by the description. Form should be “Field: <field Name>”. (Exception: if your object has a repeating set of fields – you may describe the initial field set in detail such as is done for the branch specifications fields in the Branch object).
Each object’s IDD must be shown and use the format “IDD Definition”.
An excerpt IDF using the object must be shown.
Output variables for the object must be shown (heading 4) with a heading 3 <object name> Output variables preceding.
Equations may be inserted using the Microsoft™ Equation Editor. Internally we use software called “MathType” – that also may be used for Equations. It is not desirable to number every equation. If you want to reference the equations, of course, you will need to number them – it is best to number them in plain text and then we can edit them into the rest of the documents.
Each Engineering Reference section should contain a “References” section and should be formatted in author style (not numbered).
Example References:
ASHRAE. 1993. 1993 ASHRAE Handbook – Fundamentals. Atlanta: American Society of Heating, Refrigerating, and Air-Conditioning Engineers, Inc.
Chapman, A. J. 1984. Heat Transfer, 4th Edition, New York: Macmillan Publishing Company.
Lienhard, J. H. 1981. A Heat Transfer Textbook, Englewood Cliffs, N.J.: Prentice-Hall, Inc.
McClellan, T. M., and C. O. Pedersen. 1997. Investigation of Outside Heat Balance Models for Use in a Heat Balance Cooling Load Calculation. ASHRAE Transactions, Vol. 103, Part 2, pp. 469-484.
Walton, G. N. 1983. Thermal Analysis Research Program Reference Manual. NBSSIR 83-2655. National Bureau of Standards.
Documentation content copyright © 1996-2018 The Board of Trustees of the University of Illinois and the Regents of the University of California through the Ernest Orlando Lawrence Berkeley National Laboratory. All rights reserved. EnergyPlus is a trademark of the US Department of Energy.
This documentation is made available under the EnergyPlus Open Source License v1.0.