ViaQ documentation

Table of Contents

• Project Layout
• Raising an issue
• Working on the docs
  • Requesting a change

To read the documentation, visit the web page.

To modify the documentation or use the data model for code generation, read on.

Project Layout

• src/ Edit these Asciidoc and DOT source files to modify the pages.

• src/data_model/ The data model for log record fields.

• docs/ The generated website available at the web page do not edit.

• Makefile Update docs/ to reflect changes in fsrc/

Raising an issue

You can raise an issue using GitHub issues.

However, it is better if you _request_a_change

Working on the docs

First, install or verify that you have the following software installed:

• GNU make

• asciidoctor (render AsciiDoc as HTML)

• graphviz (render .dot diagrams as .svg)github

• gomplate (apply Go templates, generate data model documentation)

Instructions for Fedora:

dnf install make graphviz asciidoctor linkchecker yamllint
go install github.com/hairyhenderson/gomplate/v3/cmd/gomplate@latest

For other platforms, figure out the equivalent installation steps.

Requesting a change

1. Clone this repository.

2. Edit or add files in src/. Documentation is written in AsciiDoc, and rendered using asciidoctor. Diagrams are written in graphviz DOT format.

3. Run make docs to render your changes as HTML in docs/. Preview your changes using a browser.

4. Run make all to re-generate everything and validate links (link checking takes a minute or two).

5. Submit a pull-request with your changes, and a brief description of why you made them.
   

The pull request will be discussed and revised before merging using the GitHub review process. It is OK to request changes that you’re are not 100% sure of. Even if your pull request needs some revisions, a concrete proposal for change often gets resolved more quickly than a general request in an issue.

Once the pull-request is merged, the contents of docs/ is automatically published to the web page using GitHub pages