search

sodadata / docs

Soda Documentation, served at docs.soda.io
https://docs.soda.io
19 stars 10 forks source link
documentation

readme

Soda documentation guidelines

Join us in our mission to help users become productive and confident using Soda software.

Contribute

The following outlines the workflow to contribute to Soda documentation.

  1. Set up docs tooling locally on your machine and clone the GitHub repo.
    OR
    skip the tooling and use Netlify preview, instead.
  2. Create a new branch for your work. Include the word docs in the name of your branch.
  3. Follow the style guidelines to edit existing or write new content using markdown.
  4. Adjust the nav order of any new files in the docs > nav.yml file.
  5. Spell check your content (select all and copy to Google Docs for a thorough check) and test all links.
  6. Commit your contributions, create a pull request, and request a review from janet-can.
  7. If you work for Soda, merge your pull request. If not, a Soda employee will review and merge when ready.
  8. Celebrate your new life as a published author!

Set up docs tooling

Soda uses the following tools to build and publish documentation.

To contribute to Soda documentation, set up your local system to author and preview content before committing it.

  1. Jekyll requires Ruby 2.4.0 or higher. If necessary, upgrade or install Ruby locally. If you are using a Mac with an Apple M1 chip, follow the prerequisite steps to set up Ruby locally.
  2. From Terminal, install two Ruby gems: bundler and jekyll. Refer to Jekyll documentation for details. 
    $ gem install --user-install bundler jekyll
  3. Clone the sodadata/docs repo from GitHub.
  4. From the command-line, navigate to the docs repo directory, then run bundle install to install all the necessary gems.
  5. Open the cloned repo locally in your favorite code editor such as Visual Code or Sublime.
  6. From the command-line, navigate to the docs repo directory that you just cloned, then run the following to build and serve docs locally. 
    $ bundle exec jekyll serve
  7. In a browser, navigate to http://localhost:4000 to see a preview of the docs site locally.
  8. When you make changes to docs files in your code editor, save the files, then refresh your browser to preview your changes. If you are creating a new page, consider copy+pasting the contents of the template-new-page.md file and pasting into your new file so that the standard header and footer info are included.

Install Ruby on Mac with an Apple M1 chip

  1. If you have not already done so, install Homebrew by running the following command in Terminal. 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Configure Terminal to run your shell as a login shell. See MacOS login shell for details.
  3. As instructed in the command-line output, run the following two commands one-by-one. Replace the target of echo to your bash profile file: 
    
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile

eval "$(/opt/homebrew/bin/brew shellenv)"

3. Optionally, run:  `brew bundle dump`.
4. Install Ruby using the following command. Note that you can use <a href="https://github.com/rbenv/rbenv/blob/master/README.md" target="_blank">`rbenv`</a> to install Ruby if you need to access multiple versions of Ruby on your machine.  
```shell
brew install ruby
  1. Check the Ruby install by running: ruby -v
  2. Add the following to your bash profile file, then save the file. 
    export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
export LDFLAGS="-L/opt/homebrew/opt/ruby/lib"
export CPPFLAGS="-I/opt/homebrew/opt/ruby/include"
export PKG_CONFIG_PATH="/opt/homebrew/opt/ruby/lib/pkgconfig"
  3. Source your freshly modified bash profile source /your/bash_profile/file or open a new Terminal window.
  4. Follow the Set up docs tooling above, starting at step 2.

Use Netlify preview

Rather than set up all the docs tooling locally to preview your work, you can use Netlify to preview your work.

  1. Clone the repo, then create a new branch and open it in your IDE.
  2. Make changes as you wish to docs files, then save and commit the changes locally.
  3. Push your branch to the repo, and Create a Pull Request.
  4. Once created and saved in GitHub, a new PR triggers a Netlify workflow that prepares a preview of the docs site that you can access via the Deploy Preview link in the PR. Use this link to review your work as it will appear when it is published.
  5. When you are satisfied with the changes, request a review of the PR from janet-can.
  6. If you work for Soda, merge your pull request. If not, a Soda employee will review and merge when ready.

Style guidelines

Soda uses the Splunk Style Guide for writing documentation. For any questions about style or language that are not listed below, refer to the Splunk Style Guide for guidance.

Language

Good practice

Formatting

Content

Image guidelines

Release note documentation

Document the details of each Soda product's release using included release note files.

  1. Create a new branch in this docs repo to create your product release notes.
  2. To the _release-notes folder in this Docs repo, add a new markdown file for your new product release notes. Follow the file naming structure established by existing files. If you do not recognize a discernable pattern, use a logical name for the feature or functionality you are releasing.
  3. Copy and paste the contents of the template-soda-cloud-rn.md file into your new file.
  4. Write your release notes using the style guide for guidance on format, language, etc. Use active voice!
  5. Spell check your content. (Copy paste to a Google Doc or your favorite editor to run a spell check.)
  6. Commit your changes, then create a new pull request when you are ready to publish.
  7. In the new pull request, request a review by @janet-can, if you wish.
  8. Any Soda employee reviews, squashes, and mergess the PR.

Use Jekyll markdown (and HTML)

Kramdown is the default markdown renderer that Jekyll uses. What follows are some Kramdown-specific formatting syntax.

Insert image:

Add a png file of your logically-named image to the docs/assets/images directory, then add this markdown to the file in which you want the image to appear:

![webhook-incident](/assets/images/webhook-incident.png){:height="440px" width="440px"}

Includes:

Add a markdown file of your logically-named include content to the docs/_includes directory, then add this markdown to the file in which you want the content to appear:

{% include disable-all-samples.md %}

Relative links:

[warehouse yaml]({% link soda/product-overview.md %})

[airflow_bash.py](/../examples/airflow_bash.py)

Link to an anchor on a different page:

[warehouse yaml]({% link soda/product-overview.md %}#to-anchor)

Link to section on same page:

[example](#example-tests-using-a-column-metric)

External link:

<a href="https://en.wikipedia.org" target="_blank">Wikipedia</a>

Comment out:

<!-- This content does not display on the web page. -->

Show code: To keep the numbered list intact, apply endraw to the end of the line of preceding text; do not prepend with a line break.

{% raw %}
{% endraw %}

Add Last modified date:

{% last_modified_at %}

Add collapse-expand toggle:

<details>
    <summary style="color:#00BC7E">Click to expand</summary>
    Long content here
    and here
</details>

Add mailto link:

<a href="https://github.com/sodadata/docs/blob/main/mailto:support@soda.io">Soda Support</a>

Add a table:

| Header - Left-aligned content | Header - Center-aligned content | Header - Right aligned content |
|---------------------| :--------------------:|---------------------:|
| Content | Content | Content | Content |

Add copy to clipboard button for code blocks:

{% include code-header.html %}

Redirect site visitors

The jekyll-redirect-from plugin enables authors to redirect users if a page is moved.

See documentation: https://github.com/jekyll/jekyll-redirect-from

To apply a redirect, navigate to the redirect destination file, then add the following to the file metadata at the top:

redirect_from: /pageyouwanttoredirect/

OR

redirect_from:
  - /pageyouwantoredirect/
  - /anotherpagetoredirect/

Troubleshoot the Search tool

docs.soda.io uses the Just The Docs for the theme which, in turn, uses lunrjs for the Search tool. Per lunrjs's documentation, “the more a search term occurs in a single document, the more that term will increase that document’s score, but the more a search term occurs in the overall collection of documents, the less that term will increase a document’s score.” There is no built-in functionality in the theme to adjust the document’s scoring relative to search terms.

Work-around: artificially add a string/search term to to a document to boost the document's search score and make it appear in the auto-complete search results.

Also, lunrjs does not take into account ocurrences of terms that appear in _includes. For the Search tool to "find" a term, the term itself must occur in the content of a served markdown file. For example, though the term regex appeared multiple times in two _includes files, the Search tool registered zero occurrences of the term in the docs. Adding the term to the content of the metrics.md and sql_metrics.md files yielded expected search results.

Jekyll SEO Tag Plugin

For static web builders like Jekyll, the one that we use, there is a plugin that automatically optimizes for SEO called Jekyll SEO Tag. It does stuff like "automatically add the appropriate search engine metadata to each page, including the page title, description, canonical URL, next and previous URLs for posts, and JSON-LD site and post metadata to help your site get properly indexed by search engines." (See this blogpost that illustrates the stuff that the Jekyll SEO Tag plugin does.)

That plugin has not been explicitly installed on our version of Jekyll. However, if you add the tag {% seo %} to your head.html file, Jekyll automatically starts applying Jekyll SEO Tag functionality. When I tested it by removing that tag, all the SEO content between the and disappeared.