Skip to content

Writing Style Guide

Jump to bottom
Dan Macumber edited this page Jul 25, 2014 · 7 revisions

Wiki ? Writing Style Guide

Contents

  1. Introduction
  2. Editing Process
  3. Writing Style
  4. Formatting

1. Introduction

Our written documentation (currently at https://github.com/NREL/OpenStudio/wiki) is OpenStudio's public face to the world. In order to project a polished and professional appearance, OpenStudio documentation needs to conform to some common standards. This document will help OpenStudio team members to write with a common style.

2. Editing Process

OpenStudio documentation is written using markdown syntax and is published by committing to the documentation repository ([email protected]:NREL/OpenStudio.wiki.git). Minor updates to existing documentation may be made by committing directly to the documentation repository. However, substantial modifications or new material should be reviewed before being published on the main documentation site. To do this, we follow some of the same procedures that we follow when working on the OpenStudio source code. Unfortunately, github does not support the same interfaces for branching and merging documentation repositories as it does for source code. Therefore, we have to modify this workflow somewhat for documentation tasks.

The first step is to create a fork of the main OpenStudio documentation repository. To do this, first make a fork of the entire NREL/OpenStudio repository on github by clicking on the Fork button. This will create a new OpenStudio repository under your github username, e.g. [email protected]:yourname/OpenStudio.git. This will also create a fork of the OpenStudio documentation repository under your github username, e.g. [email protected]:yourname/OpenStudio.wiki.git. Check out this new repository as you would check out any other repository.

Next you will need to synch your checkout of the wiki with the main OpenStudio documentation repository. TODO: git steps

You can now edit files and commit them to your repository, the pages will appear at https://github.com/yourname/OpenStudio/wiki.

When your edits are ready you can synch with the main documentation repository to ensure you are up to date and then force push your to the main documentation repository TODO: git steps

3. Writing Style

Larry these are totally wrong, just placeholders

  • Write in the present tense
  • Write in the first person
  • Address the reader as you and we
  • Use the spell checker (any common things we want to standardize on? setpoint vs set-point, etc?)
  • Blah blah blah

4. Formatting

Links to markdown syntax

Clone this wiki locally