Documentation

[rafmudaf]

The online documentation should contain all static information relevant to users, developers and project managers. Dynamic information such as collaboration and discussions will exist on GitHub, and the online documentation should be a parallel resource to that. A typical flow of information for a bit of work will be similar to the chart below.

flowchart TD
    a(GitHub Discussion) --> b(GitHub Issue - Feature Request)
    b --> c(GitHub Pull Request)
    c -.-> |Includes| d(Online Documentation)

Loading

Framework

The documentation framework should allow developers to focus on the content without concern for constructing HTML, CSS, and JavaScript code. It should support textual content as well as images, videos, and other graphical content. An important feature is the proper formatting through syntax highlighting of computer code.

Many frameworks exist that meet the requirements. Jupyter-Book is initially chosen for the following reasons:

• It is a mature project with active development and support
• Built around Sphinx so the NREL team can leverage its existing experience with that framework
• Support for markdown (.md) and restructured text (.rst)
• The default theme style is pretty good
  • Supports multiple screen sizes well
  • Includes a website search feature
  • Very common among scientific software so it is expected and well understood by users

Contents

The online documentation should contain the following sections:

• Introduction and overview of OpenTurbine
• Installation
• Getting started instructions - this is like a very brief user's guide
• Detailed user's guide
• Developer's guide

Developer's Guide

Developer's of OpenTurbine should understand the workflows described here. Adherence to these processes ensures high quality code with minimal maintenance.

Version control

OpenTurbine uses git with a basic version of git-flow. The main branch is stable, contains release-ready code, and is updated least frequently. The develop branch contains tested and well developed code. It is the staging branch for the next release. New work happens on feature branches prefixed with feature/ or f/, and these are merged into develop. Bug fixes are on branches prefixed with bug/ or b/, and these can be merged into develop or main depending on the severity of the bug.

The commit history should serve as a record of changes and include good contextual information. When staging changes and writing a commit message, ask yourself "What will this mean to me in two years?" Indeed, there is a real possibility that well after you've lost your current context you or your colleague will read through your commits in an attempt to understand what you were thinking right now. Do your future self the favor of authoring a long lasting commit message with a well-scoped set of changes.

Some tips:

• Each commit should encompass one well-scoped change. A smell test is whether you've used the work "and" in the commit message. For example, a commit message of "Add a new CLI flag for XYZ and improve speed via ABC" should probably be split into two commits, "Add new CLI flag for XYZ" and "Improve speed via ABC".
• The sequence of commits can be as meaningful as the individual changes. Construct the commit history so that someone can move through each commit in a series and understand why and how the changes were made in sequence.
• Practice editing a branch's commit history with git rebase -I.

Pull Requests

The driving question for each pull request should be "How can I convince reviewers that this pull request should be merged?"

Pull requests should include a well-scoped set of changes. It is often reasonable to split a single branch into multiple pull requests so that each PR does a single thing. The pull request should have a complete description of the change as well as its impact on the rest of the code. It is helpful to include diagrams of the new code and how it fits into the existing architecture. New code should include tests to demonstrate verification of the methodology and robustness of the implementation.

Reviewers should be very verbose in their comments and feedback. If there is a question, it should be asked without hesitation. This builds a searchable body of information that can ultimately be compiled into more formal documentation or serve as an informal reference on GitHub itself.

Developer Workflow

Prior to starting work on a new project, a Discussion should be created to describe the scope of work and design the implementation. The original post (OP) should serve as the primary document and comments should be added by reviewers. Typically, only the original author will modify the OP, but all contributors can participate in the design process with comments. Once the concept is well defined, an Issue should be opened with the final description from the Discussion.

Issues allow work to be tracked in Project boards. Issues are generally a bug report or a feature request. In addition to the information from the Design Discussion, issues should include anticipated time frame and developer assignments. This is a great place to coordinate a team of developers as well as link issues to other issues to understand dependencies.

Finally, when the work is complete, a pull request should be created. See the Pull Requests section.