Documentation workflow

The UT Dallas Cyberinfrastructure Research Computing (CIRC) documentation adheres to the docs as code philosophy. The documentation you’re reading is version controlled, tested, and reviewed both by automated software and the CIRC staff. The documentation writing process closely follows a software development cycle:

  1. An idea for a page, or a typo fix, begins as an issue on the CIRC documentation GitLab project.

  2. Someone, maybe you, writes the documentation to solve the issue in the AsciiDoc format.

  3. The author submits a merge request to the main GitLab documentation project.

  4. The newly added documentation is automatically tested. At this point, the author can revise and retest.

  5. Once the documentation passes the automated tests, two CIRC staff members review through GitLab code review.

  6. After resolving all reviews, a CIRC staff member merges the new documentation into the documentation repository’s main branch and the GitLab pipeline rebuilds and deploys the documentation website using the static site generator Antora.

Git and GitLab

The CIRC documentation lives in a public git repository. Git is a version control system which keeps files with their modification histories. CIRC hosts the documentation repository on GitLab, a platform that helps with collaboration and automatic building, testing, and deployment for code bases.

If you find a problem with the documentation or have an idea for a page, you can submit an issue in the documentation GitLab.

Adding your documentation to the project

To add a new page or update an existing page, you’ll follow three major steps: fork the project, commit your changes, and submit a merge request. For general information on git version control, see the CIRC git documentation. For a step-by-step guide to submitting documentation to the GitLab Project, see the CIRC documentation GitLab tutorial.

AsciiDoc

The CIRC documentation files are written in a plain text markup language called AsciiDoc. Using AsciiDoc means the documentation can be version controlled, linted, and processed into multiple formats. For a crash course in AsciiDoc, see the AsciiDoctor syntax quick reference.

For example, here’s what this section looks like in raw AsciiDoc:

== AsciiDoc

The CIRC documentation files are written in a plain text markup language called
https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc]. Using AsciiDoc means
the documentation can be link:#_git_and_gitlab[version controlled],
link:#_review[linted], and processed into multiple formats. For a crash course
in AsciiDoc, see the
https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoctor
syntax quick reference].

For example, here's what this section looks like in raw AsciiDoc:

[source,asciidoc]
----
Infinite recursion!
----

Documentation testing

The CIRC documentation is automatically copyedited using Vale, which checks text for writing issues based on a series of rules. This documentation adheres to the Google developer documentation style guide (see Vale implementation here) and some custom CIRC rules.

Got an idea for a rule to make the CIRC docs better? You can submit a merge request or issue to the rules repository.

Review

After a piece of documentation makes it past the automatic copyediting, two CIRC staff members review it for accuracy, consistency, and style. CIRC uses code review methods for documentation reviews.

Build

When the author resolves the final review, the new documentation gets merged into the master branch of the GitLab project, which triggers the GitLab pages pipeline. The CIRC documentation pipeline uses the static site generator Antora, along with a custom UT Dallas theme, to generate the documentation website. Antora transforms the raw AsciiDoc files into HTML files for web viewing.

You can also submit issues and merge requests to the theme project.