Documentation Improvements

[rafmudaf]

The OpenFAST documentation is a perpetual work in progress. For the past few years, there have been periodic updates and improvements but no high level planning outlining a structure, objectives, and considerations. This discussion contains some high level plans and ideas for improving the documentation. Please engage! For anyone new to OpenFAST, your perspective is invaluable. And for anybody considering contributing to the project, the documentation is an easy entry point and immensely helpful to other users.

Structure

Here's a proposed structure:

Quick Start Topics

• Installation
  • Very simple recipe for installation
  • Encourage installing from a package manager
  • Split by platform
• Interacting with the executable
• Running simple cases
  • Download a simple test case
  • Run it
  • Analyze the results (visualization, etc)

Sections

1. Installation
2. Quick Start
3. User Documentation
4. Advanced Tips / Working with OpenFAST
5. Developer Documentation
6. Open Source Models

Considerations

Windows vs macOS/Linux

The documentation contains some code snippets, but they're generally written for the platform that the person writing that bit of documentation uses.

• By default, Windows and macOS are case-insensitive while Linux (at least Ubuntu) is case-sensitive.
• The syntax for running an executable and passing flags varies: /v vs -v, for example.
• Executables may have different names depending on whether compiled in Visual Studio vs CMake (inflowwind_driver vs InflowWind_Driver)

While these nuances can be reasonably guessed or easily verified by a user, it does make the documentation confusing for very novice users of a command line environment.

Should the documentation support only one platform?
Is there a way to add the CLI for all platforms?
Maybe include commands for one platform and have a document describing how to convert to the other?

See #665

Input files throughout documentation

There are various input files included in links throughout the documentation. These might be better to aggregate in a single place (another repo?) and link from the docs. The current problem is that these input files are not executed automatically, so somebody needs to remember to update them when the API changes. For example, currently (latest release is v3.2), the InflowWind input file in the appendix is out of date since v2.5.

[bjonkman]

Some thoughts:

• Documenting Linux, macOS, and Windows syntax for commands where they are different would be my preference. Intel documentation does this, though the current formatting could be better.
• I think we should attempt to standardize the executable names as much as possible. If it's just the upper/lower case that is different between cmake and Visual Studio builds, that should be easy to fix. Some of the Visual Studio builds also add the platform name (Win32 or x64), so that would take a little more effort. It would be nice if the cmake and Visual Studio solutions would build executables with the same names so the documentation wouldn't need to differentiate how the executable was built.
• There are also template input files in the matlab_toolbox repo that are used to convert OpenFAST input files to newer versions. I have been thinking we could get rid of the templates in matlab_toolbox and use the input files in the OpenFAST documentation as templates instead. (I haven't done it yet because--as of now--the documentation doesn't have examples for all of the modules, but I have been attempting to update the existing examples using the templates from matlab_toolbox whenever I update r-test). We'd have to make sure we actually use those templates though, or they will continue to risk being outdated. If you do choose to aggregate the input files in another repo, we should also update matlab_toolbox.

[rafmudaf]

On the multiple platforms, I'd love a toggle switch on the documentation that would change all the code snippets from Windows to Unix. However, that level of web development is beyond me. The Intel documentation is good for describing a flag, but for a long list of commands it can be noisy to have the code block listed twice.
I completely agree on syncing the names of executables between CMake and Visual Studio.

[rafmudaf]

If a Registry documentation is created, include the info in #1248 (comment).

[rafmudaf]

Here's a nice description of a framework for structuring documentation: https://diataxis.fr. The gist is that documentation could be broken into four sections:

• Tutorials
• How-to guides
• Explanation
• Reference

Each section has its own unique objectives but they all relate to each in some ways. I'm working on structuring the FLORIS documentation in this way, so check back there for a reference in the future if this is of interest.