Skip to content

Writing Documentation

Jump to bottom
stephen-frank edited this page Sep 15, 2014 · 35 revisions

Writing Documentation

There are four primary types of documentation associated with the Campus Energy Modeling project: the wiki (which you are currently reading), demonstration README files, MATLAB function help, and Simulink block help. For consistency, please adhere to the guidelines posted here when developing documentation.

The Wiki

The GitHub wiki for the CampusModeling repository serves as the primary source of documentation for the project. GitHub uses the Gollum wiki engine. Gollum supports the same markup formats as GitHub's internal rendering engine; for this wiki we prefer GitHub Flavored Markdown (GFM).

Access

There are two ways to access (and edit) the Campus Modeling wiki:

  1. On the web via the NREL GitHub
  2. By cloning the wiki using Git

For reading and simple editing, the web interface is sufficient. More complex tasks, such as adding image files and reorganizing the directory tree, require the full Git interface. Note: unless you have Gollum installed locally, you'll need to push changes in order to view the rendered results.

Organization

Conceptually, the Campus Modeling wiki consists of two documents: a user guide and a developer guide. The directory structure for the wiki reflects this organization:

  • / The root directory; contains the wiki main page, Home.md
  • /dev-guide/ The home directory for pages that are part of the developer guide
  • /user-guide/ The home directory for pages that are part of the user guide
  • /image/ Directory for storing image files
  • /pdf/ Directory for storing PDF documents

For wiki links, Gollum parses spaces and slashes as dashes to determine the file name. For example, the source for this page is named Writing-Documentation.md.

Please keep images seperate from the page source files. Also, per Gollum requirements, each wiki page file must have a unique name (even if located in a subdirectory).

Editing

Prior to editing, please review the documentation for:

When editing, please:

  • Keep documentation short and simple.
  • Use complete sentences and proper grammar. This facilitates reading comprehension.
  • Make the page source human readable. Use consistent indenting, avoid embedded HTML tags, etc.
  • Use Unicode (rather than HTML) for symbols and units. For example, use α for alpha, m² for square meters, and ℃ for degrees Celsius.

When creating new pages, please use the full Git interface so that you can place the pages under the appropriate folder (user-guide or dev-guide). (Following red links from the web interface creates the files in the root directory.)

README Files

Each demo folder should include a README file (named README.txt) which briefly documents the demo. The file should follow this template:

Include a brief description of the demo. (A few sentences.)

Features:
•   Major feature 1
•   Major feature 2

Requirements:
•   MATLAB/Simulink (R2013a)
•   Campus Energy Modeling project MATLAB/Simulink library
•   etc.

Instructions: 
1.  Open MATLAB and set the working directory to the folder that contains this README file.
2.  Second step.
3.  etc.

Comments:
1.  Additional comments go here, numbered in order.
2.  Second comment.

The Features section highlights the major features in the demo. The Requirements section lists all software required in order to run the demo, including the Campus Energy Modeling MATLAB/Simulink library. This is particularly important for demos with outside software dependencies, such as EnergyPlus. The Instructions section walks the user through executing the demo; see Creating Demos for more information. Comments is optional and can be used to document any additional information the user may need or want.

Editing guidelines:

  • Hard wrap lines in the help field at some reasonable number of characters (for example, 100).
  • Use Unicode for symbols and units. For example, use α for alpha, m² for square meters, and ℃ for degrees Celsius.
  • For consistent rendering, use spaces rather than tabs for indented text.

MATLAB Function Help

MATLAB functions are self-documented using MATLAB's built-in function help syntax. For consistency among the functions in the project, please use the following template:

%% MYTESTFUNCTION - One line description of function
%
% More extensive description of the function follows on subsequent lines.
% Leave a space between the header line and descriptive paragraph for
% better formatting in MATLAB's help browser.
%
% Multiple descriptive paragraphs are fine.
%
% SYNTAX:
%   y = myTestFunction(x)
%
% INPUTS:
%   x =         The number to increment
%
% OPTIONAL INPUTS:
%   [If the function has optional inputs, describe them here]
%
% OUTPUTS:
%   y =         Equals x + 1
%
% EXAMPLES:
%   a = myTestFunction(1)	% Returns a = 2
%
% COMMENTS:
% 1. Reserve any extensive comments for the comments section.
%
% 2. Number comments sequentially.
%
% 3. The OPTIONAL INPUTS, EXAMPLES, COMMENTS, and REFERENCES sections are
%    optional.
%
% REFERENCES:
% 1. First reference (in citation format of your choice)
%
% 2. Second reference

function y = myTestFunction(x)
    %% Function Body
    % Increment x
    y = x + 1;
    
    % y is returned
end

Use all capitals for the function name at the top of the help block. MATLAB's help browser does not format the function help. Therefore, the author is responsible for formatting:

  • Manually align the variable descriptions in the INPUTS and OUTPUTS sections.
  • Manually align and space numbered lists.
  • For consistency with the MATLAB editor, hard wrap lines at 75 characters.

The OPTIONAL INPUTS, EXAMPLES, COMMENTS, and REFERENCES sections are optional.

Simulink Block Help

The Simulink block mask editor has documentation fields for the mask type, a mask description, and mask help (see figure).

Title and Description

The mask type and description appear in the block dialog as a title and description (see figure).

No formatting is supported. Use title case for the mask type (title) and match the title to the name of the name of the block in the Simulink library. Keep the mask description short; reserve extensive commentary for the help. Some unicode characters are allowed, but test the result by saving and reloading the library. Do not hard wrap lines in the description; Simulink's block dialog will automatically wrap lines.

Browser-based Help

Unlike MATLAB function help, Simulink block help opens in the MATLAB web browser as HTML. HTML markup is supported, but unfortunately not any simpler (or more human readable) markup syntax. For consistency among the blocks in the library, please use the following template for the help:

Provide a short phrase which summarizes the block's function. 

<h2>Description</h2>
Provide one or more descriptive paragraphs.

<h2>Requirements</h2>
If the block has requirements apart from MATLAB and Simulink, list them here, with hyperlinks.

<h2>Input</h2>
Describe the input(s) to the block. Use <b>bold text</b> to highlight names or brief descriptions of specific inputs.

Alternatively, list the inputs using a descriptive list:
<dl>
  <dt><b>First input</b></dt><dd>Description of first input</dd>
  <dt><b>Second input</b></dt><dd>Description of second input</dd>
</dl>

<h2>Output</h2>
Describe the output(s) from the block. Use <b>bold text</b> to highlight names or brief descriptions of specific outputs.

Alternatively, list the outputs using a descriptive list:
<dl>
  <dt><b>First output</b></dt><dd>Description of first output</dd>
  <dt><b>Second output</b></dt><dd>Description of second output</dd>
</dl>

<h2>Physical Ports</h2>
Describe the block's physical port(s). Use <b>bold text</b> to highlight names or brief descriptions of specific ports.

Alternatively, list the physical ports using a descriptive list:
<dl>
  <dt><b>First port</b></dt><dd>Description of first port</dd>
  <dt><b>Second port</b></dt><dd>Description of second port</dd>
</dl>

<h2>Parameters</h2>
List or describe the block parameters. If necessary, explain the organization of the mask dialog. Use <b>bold text</b> to highlight names or brief descriptions of specific parameters.

Alternatively, list the parameters using a descriptive list:
<dl>
  <dt><b>First parameter</b></dt><dd>Description of first parameter</dd>
  <dt><b>Second parameter</b></dt><dd>Description of second parameter</dd>
</dl>

<h2>Comments</h2>
<ol>
  <li>This is the first comment. Use an ordered list for comments.</li>
  <li>This is the second comment.</li>
</ol>

Alternatively, include a single, essay-style comment which covers all relevant material.

<h2>References</h2>
<ol>
  <li>First reference (in citation format of your choice)</li>
  <li>Second reference</li>
</ol>

The Comments and References sections are optional. The Input, Output, and Physical Ports sections may be excluded if the block has no inputs, outputs, or physical ports, respectively.

Additional editing guidelines:

  • Do not hard wrap lines in the help field. Hard wraps render poorly in the MATLAB web browser.
  • Use HTML entities (rather than Unicode) for symbols and units. This guideline applies only to Simulink block help. Although recent MATLAB versions support Unicode, Simulink files with the .mdl extension will corrupt certain Unicode characters on save and/or load.
  • If including references, use HTML to format them properly for browser display.

For efficiency, you may wish to edit the HTML help in an external text editor or an online editor (such as w3school's Tryit Editor), then paste the finished result into the block mask editor. The table below gives examples of HTML entities for some common symbols and units:

Symbol HTML Code
² &sup2;
³ &sup3;
° &deg;
− &minus;
± &plusmn;
π &pi;

Clone this wiki locally