diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 567d11e083..aa46627a82 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -8,7 +8,7 @@ Fixes #[insert issue link, if any]
# Writing help
-For information about style and word usage, see the [style guide](https://docs.timescale.com/about/latest/contribute-to-docs/)
+For information about style and word usage, see the [Contribution guide](https://github.com/timescale/docs/blob/latest/CONTRIBUTING.md)
# Review checklists
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5d2be4e9bc..f65a02313e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,202 +1,190 @@
-# Introduction
+# Contribute to Timescale documentation
-There are multiple ways to help make Timescale better, including contributing
-to the documentation. All of our documentation is available to use and review
-with GitHub.
+Timescale documentation is open for contribution from all community members. The current source is in this repository.
-## First contribution
+This page explains the process and guidelines to follow when contributing to Timescale documentation.
-You can make contributions to the documentation by creating a fork of the
-repository. However, if you have write access to the repository, use a branch
-instead. Some of our automation does not work correctly on forks.
+## Contribution process
-
+You can contribute to Timescale documentation in the following ways:
-### Contributing using a fork
+- [Create an issue][docs-issues] in this repository and describe the proposed change. Our doc team will take care of it.
+- Update the docs yourself and have your change reviewed and published by our doc team.
-1. Make sure you have a [GitHub](https://github.com) account, and that
- you're signed in.
-1. Navigate to the
- [Timescale documentation repo](https://github.com/timescale/docs),
- click the `Fork` button in the top-right corner, and select the account you
- want to use.
-1. Wait for GitHub to create your fork and redirect you.
-1. Clone the repository to your local machine. To find this URL, click the green
- `Code` button and copy the HTTPS URL:
+To make the contribution yourself:
- ```bash
- git clone https://github.com//docs.git
- ```
+1. Get the documentation source:
+
+ - No write access? [Fork this repository][github-fork].
+ - Already have a write access? [Clone this repository][github-clone].
-1. List the current remote branches:
+2. Create a branch from `latest`, make your changes, and raise a pull request back to `latest`.
- ```bash
- git remote -v
- ```
+3. Sign a Contributor License Agreement (CLA).
- This command should list two remotes, both marked `origin`, like this:
+ You have to sign the CLA only the first time you raise a PR. This helps to ensure that the community is free to use your contributions.
+
+4. Review your changes.
- ```bash
- origin https://github.com//docs.git (fetch)
- origin https://github.com//docs.git (push)
- ```
+ The documentation site is generated in a separate private repository using [Gatsby][gatsby]. Once you raise a PR for any branch, GitHub will **automatically** generate a preview for your changes and attach the link in the comments. Any new commits will be visible at the same URL. If you don't see the latest changes, try an incognito browser window. Automated builds are not available for PRs from forked repositories.
- The `origin` remotes are your own fork, and you can do whatever you want
- here without changing the upstream repository.
-1. Add the docs repo as an upstream:
+## Language
- ```bash
- git remote add upstream https://github.com/timescale/docs.git
- ```
+Write in a clear, concise, and actionable manner. Timescale documentation uses the [Google Developer Documentation Style Guide][google-style] with the following exceptions:
-1. Check:
+- Do not capitalize the first word after a colon.
+- Use code font (back ticks) for UI elements instead of semi-bold.
- ```bash
- git remote -v
- ```
+## Edit individual pages
- This command should now have the same two `origin` remotes as before, plus
- two more labelled `upstream`, like this:
+Each major doc section has a dedicated directory with `.md` files inside, representing its child pages. This includes an `index.md` file that serves as a landing page for that doc section by default, unless specifically changed in the navigation tree. To edit a page, modify the corresponding `.md` file following these recommendations:
- ```bash
- origin https://github.com//docs.git (fetch)
- origin https://github.com//docs.git (push)
- upstream https://github.com/timescale/docs.git (fetch)
- upstream https://github.com/timescale/docs.git (push)
- ```
+- **Regular pages** should include:
-1. Fetch the branches in the upstream repository:
+ - A short intro describing the main subject of the page.
+ - A visual illustrating the main concept, if relevant.
+ - Paragraphs with descriptive headers, organizing the content into logical sections.
+ - Procedures to describe the sequence of steps to reach a certain goal. For example, create a Timescale service.
+ - Other visual aids, if necessary.
+ - Links to other relevant resources.
- ```bash
- git fetch upstream
- ```
+- **API pages** should include:
-1. Merge the changes from the upstream `latest` branch, into your fork's
- `latest` branch:
+ - The function name, with empty parentheses if it takes arguments.
+ - A brief, specific description of the function, including any possible warnings.
+ - One or two samples of the function being used to demonstrate argument syntax.
+ - An argument table with `Name`, `Type`, `Default`, `Required`, `Description` columns.
+ - A return table with `Column`, `Type`, and `Description` columns.
- ```bash
- git merge upstream/latest
- ```
+- **Troubleshooting pages** are not written as whole Markdown files, but are programmatically assembled from individual files in the`_troubleshooting` folder. Each entry describes a single troubleshooting case and its solution, and contains the following front matter:
+
+ |Key| Type |Required| Description |
+ |-|-------|-|--------------------------------------------------------------------------|
+ |`title`| string |✅| The title of the troubleshooting entry, displayed as a heading above it |
+ |`section`| The literal string `troubleshooting` |✅| Must be `troubleshooting`, used to identify troubleshooting entries during site build |
+ |`products` or `topics`| array of strings |✅ (can have either or both, but must have at least one)| The products or topics related to the entry. The entry will show up on the troubleshooting pages for the listed products and topics. |
+ |`errors`| object of form `{language: string, message: string}` |❌| The error, if any, related to the troubleshooting entry. Displayed as a code block right underneath the title. `language` is the programming language to use for syntax highlighting. |
+ |`keywords`| array of strings |❌| These are displayed at the bottom of every troubleshooting page. Each keyword links to a collection of all pages associated with that keyword. |
+ |`tags`| array of strings |❌| Concepts, actions, or things associated with the troubleshooting entry. These are not displayed in the UI, but they affect the calculation of related pages. |
+
+ Beneath the front matter, describe the error and its solution in regular Markdown. You can also use any other components allowed within the docs site.
+
+ The entry shows up on the troubleshooting pages for its associated products and topics. If the page doesn't already exist, add an entry for it in the page
+ index, setting `type` to `placeholder`. See [Navigation tree](#navigation-tree).
-1. Create a new branch for the work you want to do. Make sure you give it an
- appropriate name, and include your username:
+## Edit the navigation hierarchy
- ```bash
- git checkout -b update-readme-username
- ```
+The navigation hierarchy of a doc section is governed by `page-index/page-index.js` within the corresponding directory. For example:
-
+```js
+ {
+ title: "Timescale Cloud services",
+ href: "services",
+ excerpt: "About Timescale Cloud services",
+ children: [
+ {
+ title: "Services overview",
+ href: "service-overview",
+ excerpt: "Timescale services overview",
+ },
+ {
+ title: "Service explorer",
+ href: "service-explorer",
+ excerpt: "Timescale services explorer",
+ },
+ {
+ title: "Troubleshooting Timescale services",
+ href: "troubleshooting",
+ type: "placeholder",
+ },
+ ],
+ },
+```
-
+See [Use Timescale section navigation][use-navigation] for reference.
-### Committing changes and creating a pull request
+To change the structure, add or delete pages in a section, modify the corresponding `page-index.js`. An entry in a `page-index.js` includes the following fields:
-1. Make your changes.
-1. Add the updated files to your commit:
+| Key | Type | Required | Description |
+|--------------------|-----------------------------------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `href` | string | ✅ | The URL segment to use for the page. If there is a corresponding Markdown file, `href` must match the name of the Markdown file, minus the file extension. |
+| `title` | string | ✅ | The title of the page, used as the page name within the TOC on the left. Must be the same as the first header in the corresponding Markdown file. |
+| `excerpt` | string | ✅ | The short description of the page, used for the page card if `pageComponents` is set to `featured-cards`. Should be up to 100 characters. See `pageComponents` for details. |
+| `type` | One of `[directory, placeholder, redirect-to-child-page]` | ❌ | If no type is specified, the page is built as a regular webpage. The structure of its children, if present, is defined by `children` entries and the corresponding structure of subfolders. If the type is `directory`, the corresponding file becomes a directory. The difference of the directory page is that its child pages sit at the same level as the `directory` page. They only become children during the site build. If the type is `placeholder`, the corresponding page is produced programmatically upon site build. If not produced, the link in the navigation tree returns a 404. In particular, this is used for troubleshooting pages. If the type is `redirect-to-child-page`, no page is built and the link in the navigation tree goes directly to the first child. |
+| `children` | Array of page entries | ❌ | Child pages of the current page. For regular pages, the children should be located in a directory with the same name as the parent. The parent is the `index.md` file in that directory. For`directory` pages, the children should be located in the same directory as the parent. |
+| `pageComponents` | One of `[['featured-cards'], ['content-list']]` | ❌ | Any page that has child pages can list its children in either card or list style at the bottom of the page. Specify the desired style with this key. |
+| `featuredChildren` | Array of URLs | ❌ | Similar to `pageComponents`, this displays the children of the current page, but only the selected ones. |
+| `index` | string | ❌ | If a section landing page needs to be different from the `index.md` file in that directory, this field specifies the corresponding Markdown file name. |
- ```bash
- git add .
- ```
+## Reuse text in multiple pages
-1. Commit your changes:
+Partials allow you to reuse snippets of content in multiple places. All partials
+live in the `_partials` top-level directory. To make a new partial, create a new
+`.md` file in this directory. The filename must start with an underscore. Then import it into the target page and reference in the relevant place. See [Formatting examples][formatting].
- ```bash
- git commit -m "Commit message here"
- ```
+## Formatting
-1. Push your changes:
+In addition to all the [regular Markdown formatting][markdown-syntax], the following elements are available for Timescale docs:
- ```bash
- git push
- ```
+- Procedure blocks
+- Highlight blocks
+- Tabs
+- Code blocks without line numbers and the copy button
+- Multi-tab code blocks
+- Tags
+
+See [Formatting examples][formatting] for how to use them.
- If git prompts you to set an upstream in order to push, use this command:
+## Variables
+
+Timescale documentation uses variables for its product names, features, and UI elements in Timescale Console with the following syntax: `$VARIABLE_NAME`. Variables do not work inside the following:
+
+- Front matter on each page
+- HTML tables and tabs
+
+See the [full list of available variables][variables].
+
+## Links
+
+- Internal page links: internal links do not need to include the domain name `https://docs.timescale.com`. Use the `:currentVersion:` variable instead of `latest` in the URL.
+- External links: input external links as is.
+
+See [Formatting examples][formatting] for details.
+
+## Visuals
+
+When adding screenshots to the docs, aim for a full-screen view to provide better context. Reduce the size of your browser so there is as little wasted space as possible.
+
+Attach the image to your issue or PR, and the doc team will upload and insert it for you.
+
+## SEO optimization
+
+To make a documentation page more visible and clear for Google:
+
+- Include the `title` and `excerpt` meta tags at the top of the page. These represent meta title and description required for SEO optimization.
- ```bash
- git push --set-upstream origin
- ```
+ - `title`: up to 60 characters, a short description of the page contents. In most cases a variation of the page title.
+ - `excerpt`: under 200 characters, a longer description of the page contents. In most cases a variation of the page intro.
-1. Create a pull request (PR) by navigating to
- and clicking
- `Compare and Create Pull Request`. Write an informative commit message
- detailing your changes, choose reviewers, and save your PR. If you haven't
- yet finished the work you want to do, make sure you create a draft PR by
- selecting it from the drop down box in the GitHub web UI. This lets your
- reviewers know that you haven't finished work yet, while still being
- transparent about what you are working on, and making sure we all understand
- current progress.
+- Summarize the contents of each paragraph in the first sentence of that paragraph.
+- Include main page keywords into the meta tags, page title, first header, and intro. These are usually the names of features described in the page. For example, for a page dedicated to creating hypertables, you can use the keyword **hypertable** in the following way:
-
+ - Title: Create a hypertable in Timescale Cloud
+ - Description: Turn a regular PostgreSQL table into a hypertable in a few steps, using Timescale Console.
+ - First header: Create a hypertable
-
-Choose your reviewers carefully! If you have made changes to the technical
-detail of the documentation, choose an appropriate subject matter expert (SME)
-to review those changes. Additionally, every change requires at least one
-documentation team member to approve. Ask the documentation team for a review by
-adding the `timescale/documentation` group as a reviewer.
-
+## Docs for deprecated products
-## Second contribution
-
-When you have checked out the repo, if you want to keep working on things, you
-need to make sure that your local copy of the repo stays up to date. If you
-don't do this, you *will* end up with merge conflicts.
-
-
-
-### Second contribution
-
-1. Check out your fork's `latest` branch:
-
- ```bash
- git checkout latest
- ```
-
- You get a message like this:
-
- ```bash
- Switched to branch 'latest'
- Your branch is up to date with 'origin/latest'.
- ```
-
- BEWARE! This is usually a lie!
-1. Fetch the branches in the upstream repository:
-
- ```bash
- git fetch upstream
- ```
-
-1. Merge the changes from the upstream `latest` branch, into your fork's
- `latest` branch:
-
- ```bash
- git merge upstream/latest
- ```
-
-1. If you are continuing work you began earlier, check out the branch that
- contains your work. For new work, create a new branch. Doing this regularly
- as you are working means you keep your local copies up to date and avoid
- conflicts. You should do it at least every day before you begin work, and
- again whenever you switch branches.
-
-
-
-
-Never leave branches lying around on your local system. Create your PR as soon
-as possible, and make good use of the Draft feature. Commit to your feature
-branch early and often! Update your local copy from latest whenever you switch
-branches.
-
-
-## Reviewing standards
-
-When you create a pull request, a member of the documentation team will review
-it for accuracy and adherance to our standards. You can see a list of the things
-that reviewers check for in the pull request template.
-
-## Writing standards
-
-Timescale has comprehensive writing and style standards, that are constantly
-being updated and improved. For the current guidelines, see
-[contributing to documentation](https://docs.timescale.com/about/latest/contribute-to-docs/).
+The previous documentation source is in the deprecated repository called [docs.timescale.com-content][legacy-source].
+[legacy-source]: https://github.com/timescale/docs.timescale.com-content
+[docs-issues]: https://github.com/timescale/docs/issues
+[github-fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
+[github-clone]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
+[gatsby]: https://www.gatsbyjs.com/
+[google-style]: https://developers.google.com/style
+[markdown-syntax]: https://www.markdownguide.org/extended-syntax/
+[github-docs]: https://github.com/timescale/docs
+[use-navigation]: use-timescale/page-index/page-index.js
+[formatting]: _partials/_formatting_examples.md
+[variables]: https://docs.timescale.com/variables-for-contributors/
\ No newline at end of file
diff --git a/README.md b/README.md
index 6148df9aca..3fc140ce91 100644
--- a/README.md
+++ b/README.md
@@ -196,23 +196,23 @@ Where you need the partial to display, insert it as a self-closing tag:
To maintain consistency, please follow these general rules.
* Maintain text editor width for paragraphs at 80 characters. We ask you to do
-this to assist in reviewing documentation changes. When text is very wide, it
-is difficult to visually see where text has changed within a paragraph and keeping
-a narrow width on text assists in making PRs easier to review. **Most editors such
-as Visual Studio Code have settings to do this visually.**
+ this to assist in reviewing documentation changes. When text is very wide, it
+ is difficult to visually see where text has changed within a paragraph and keeping
+ a narrow width on text assists in making PRs easier to review. **Most editors such
+ as Visual Studio Code have settings to do this visually.**
* Most links should be reference-style links where the link address is at the
-bottom of the page. The two exceptions are:
+ bottom of the page. The two exceptions are:
* Links within highlight blocks (Note, Important, or Warning). These must be inline links for now
* Links to anchors on the same page as the link itself.
* All functions, commands and standalone function arguments (ex. `SELECT`,
-`time_bucket`) should be set as inline code within backticks ("\`command\`").
+ `time_bucket`) should be set as inline code within backticks ("\`command\`").
* Functions should not be written with parentheses unless the function is
-being written with arguments within the parentheses.
+ being written with arguments within the parentheses.
* "PostgreSQL" is the way to write the elephant database name, rather than
-"Postgres." "TimescaleDB" refers to the database, "Timescale" refers to the
-company.
+ "Postgres." "TimescaleDB" refers to the database, "Timescale" refers to the
+ company.
* Use backticks when referring to the object of a user interface action.
-For example: Click `Get started` to proceed with the tutorial.
+ For example: Click `Get started` to proceed with the tutorial.
### Callout and highlight blocks
@@ -264,7 +264,7 @@ Used to indicate an optional step within a procedure. Syntax: ``
Multi-code blocks are code blocks with a language or OS selector. For syntax,
see [the multi-code-block example](./_multi-code-block.md).
-### Tabs
+### Tabs
Tabs can be used to display content that differs based on a user selection. The
syntax is:
@@ -329,3 +329,7 @@ There is a specific format for the API section which consists of:
* One or two literal examples of the function being used to demonstrate argument syntax.
See the API file to get an idea.
+
+
+
+
diff --git a/_multi-code-block.md b/_multi-code-block.md
index fe2c36d061..d638a5123e 100644
--- a/_multi-code-block.md
+++ b/_multi-code-block.md
@@ -34,4 +34,4 @@ def different_python:
-
+
\ No newline at end of file
diff --git a/_partials/_deprecated.md b/_partials/_deprecated.md
index c07cc2db29..53763784a1 100644
--- a/_partials/_deprecated.md
+++ b/_partials/_deprecated.md
@@ -1,5 +1,7 @@
+
This section describes a feature that is deprecated on Timescale. We strongly
recommend that you do not use this feature in a production environment. If you
need more information, [contact us](https://www.timescale.com/contact/).
+
diff --git a/_partials/_formatting_examples.md b/_partials/_formatting_examples.md
new file mode 100644
index 0000000000..486b3087af
--- /dev/null
+++ b/_partials/_formatting_examples.md
@@ -0,0 +1,167 @@
+# Formatting examples
+
+This page illustrates and provides examples of the formatting available for Timescale documentation. Note that for most elements, spacing is important.
+
+## Procedure
+
+Use for a logical sequence of steps to achieve a goal. For example, create a hypertable.
+
+
+
+See a [use example][data-tiering] in the docs.
+
+## Highlight blocks
+
+Use sparingly and only if it's essential to attract the reader's attention.
+
+- Note
+
+ 
+
+ See a [use example][disable-chunk-skipping] in the docs.
+
+- Important
+
+ 
+
+ See a [use example][decompress-chunks] in the docs.
+
+- Warning
+
+ 
+
+ See a [use example][alerting] in the docs.
+
+- Deprecation
+
+ 
+
+ See a [use example][deprecation] in the docs.
+
+- Cloud
+
+ 
+
+ Syntax example:
+
+ ```text
+
+
+ A note dealing specifically with Timescale Cloud.
+
+
+ ```
+
+## Tabs
+
+
+
+See a [use example][live-migration] in the docs.
+
+## Code blocks
+
+As a default, use [fenced Markdown code blocks][fenced-code-blocks]:
+
+
+
+To remove line numbers and the copy button, use the `CodeBlock` component with `canCopy` and `showLineNumbers` set to `false`:
+
+
+
+See a [use example][aggregation] in the docs.
+
+## Multi-tab code blocks
+
+
+
+Syntax example:
+
+
+
+
+
+ ```ruby
+ ruby code
+ ```
+
+
+
+
+
+ ```python
+ pyhon code
+ ```
+
+
+
+
+
+ ```go
+ different python code
+ ```
+
+
+
+
+
+## Tags
+
+- Download
+
+ 
+
+ See a [use example][installation-windows] in the docs.
+
+- Experimental
+
+ 
+
+ See a [use example][time-bucket] in the docs.
+
+- Toolkit
+
+ 
+
+ See a [use example][time-weighted-average] in the docs.
+
+- Community
+
+ 
+
+ See a [use example][remove-reorder-policy] in the docs.
+
+- Hollow
+
+ 
+
+ Syntax example:
+
+ ```text
+ Text to display in a tag
+ ```
+
+## Partials
+
+Import a partial from the `_partials` directory and then reference it in the relevant part of the page. See a [use example][live-migration] in the docs.
+
+## Links
+
+Links should be [reference-style Markdown links][reference-links]. For example:
+
+[A link to the data tiering section in docs][data-tiering]
+
+[data-tiering]: ../use-timescale/data-tiering/enabling-data-tiering.md
+[disable-chunk-skipping]: ../api/disable_chunk_skipping.md
+[decompress-chunks]: ../use-timescale/compression/decompress-chunks.md
+[alerting]: ../use-timescale/alerting.md
+[deprecation]: ../_partials/_deprecated.md
+[live-migration]: ../migrate/live-migration.md
+[fenced-code-blocks]: https://www.markdownguide.org/extended-syntax/#fenced-code-blocks
+[aggregation]: ../getting-started/test-drive-timescale-features.md
+[installation-windows]: ../self-hosted/install/installation-windows.md
+[time-bucket]: ../api/time_bucket_ng.md
+[time-weighted-average]: ../api/time-weighted-averages.md
+[remove-reorder-policy]: ../api/remove_reorder_policy.md
+[reference-links]: https://www.markdownguide.org/basic-syntax/#reference-style-links
+
+
diff --git a/_procedure-block.md b/_procedure-block.md
index 38921bc352..ef01fc2e8d 100644
--- a/_procedure-block.md
+++ b/_procedure-block.md
@@ -16,13 +16,13 @@
```
3. TimescaleDB is a time-series database, built on top of PostgreSQL. More than that,
-however, it's a relational database for time-series. Developers who use TimescaleDB
-get the benefit of a purpose-built time-series database, plus a classic relational
-database (PostgreSQL), all in one, with full SQL support.
+ however, it's a relational database for time-series. Developers who use TimescaleDB
+ get the benefit of a purpose-built time-series database, plus a classic relational
+ database (PostgreSQL), all in one, with full SQL support.
```python
def start:
print('start')
```
-
+
\ No newline at end of file
diff --git a/about/contribute-to-docs.md b/about/contribute-to-docs.md
deleted file mode 100644
index 77b187d512..0000000000
--- a/about/contribute-to-docs.md
+++ /dev/null
@@ -1,524 +0,0 @@
----
-title: Contribute to Timescale documentation
-excerpt: Advice and style guide for contributing to Timescale documentation
-products: [cloud, mst, self_hosted]
-keywords: [contribute]
-tags: [docs, style guide]
----
-
-# Contributing to Timescale documentation
-
-Timescale documentation is hosted in a [GitHub repository][github-docs] and is
-open for contribution from all community members. If you find errors or would
-like to add content to our docs, you can create a pull request using GitHub for
-review by our documentation team. This document contains everything you need to
-know about our writing style and standards, but don't worry too much if you
-aren't sure what to write. Our documentation team helps you craft the
-perfect words when you have a PR ready. We also have some automation on our
-repository to help you.
-
-If you want to make minor changes to docs, such as fixing a typo, you can make
-corrections and submit pull requests on the GitHub website. Go to the file you
-want to correct and click the 'pencil' icon to edit. Make the corrections, and
-use the options at the bottom of the page to submit a pull request.
-
-To make larger changes to the documentation, follow the instructions in
-our [Contributors' Guide][contributors].
-
-For technical details about the repository, including understanding how the
-repository is organized, and the various markup and formatting conventions, see
-the [README][readme].
-
-Before we accept any contributions, Timescale contributors need to sign the
-Contributor License Agreement (CLA). By signing a CLA, we can ensure that the
-community is free and confident in its ability to use your contributions. You
-are prompted to sign the CLA during the pull request process.
-
-## Resources
-
-When making style decisions, consult resources in this order:
-
-1. This guide: always check this guide first, it contains project-specific
- guidance, and in some cases differs from the other resources listed here.
-1. The [Google Developer Documentation Style Guide][google-style]: for most
- general style guidance, we rely on the style defined here.
-1. The Chicago Manual of Style: we use this guide for some formatting decisions
- that are not covered in other resources
-1. Merriam-Webster: Timescale documentation is written in US English, for
- spelling and definitions, consult the dictionary.
-
-## Language
-
-We use standard US English, with an emphasis on plain (or classical) language,
-in simple present tense, using the second person singular ("you"). We prefer the
-active voice, but do not be afraid to use the passive voice if it serves a
-purpose. Always choose the simplest and clearest language, regardless of whether
-it's passive or active voice.
-
-For example, here are three ways of writing one sentence:
-
-* Natural English: In order to perform X installation process, please ensure
- that all of the following steps are done ...
-* Tech writer's English: To perform the X installation process, verify you
- have done the subsequent steps ...
-* Plain English: To install X, do these steps ...
-
-Remember that the order of words is important in English. Put the most important
-part of a sentence first, this is usually the actor or the action. Use the
-second part of the sentence to give it a focus: what else should the reader
-notice?
-
-Readers are often in an agitated state by the time they get to our
-documentation. Stressed readers jump around in the text, skip words, steps, or
-paragraphs, and can quickly give up if things seem too complex. To mitigate
-this, use short sentences, plain language, and a minimum number of eye-catching
-details such as admonitions.
-
-Never assume that because you've explained something earlier in a document,
-readers know it later in the document. You can use cross-references to help
-guide readers to further information if they need it.
-
-## Grammar
-
-Grammar rules are tacit evolving conventions. They have no implicit value by
-themselves, they only gain value because everyone is doing it.
-
-There are no hard and fast rules about dangling participles, split infinitives,
-or ending sentences with prepositions. Obeying these rules can often make
-language clearer but, in some cases, they make language more complicated. In
-that case, feel free to ignore them.
-
-## Headings
-
-All headings should be written in sentence case: capitalize only the first word
-in the heading, and proper nouns.
-
-For top-level page headings, and most section headings, use the simplest noun
-phrase possible. For example, instead of "Using hypertables", call the page
-"Hypertables".
-
-For level two sections that contain one or more procedures, use a simple verb
-phrase. For example, "Install Timescale". For the associated procedures, use a
-level three heading, with the gerund form of the same heading. For example,
-"Installing Timescale".
-
-## Lists
-
-You can use bulleted or numbered lists to present information. If you are unsure
-whether to use bullets or numbers, apply the test, "is the order important?" If
-the order is important, use numbers. If the list items can be read in any order,
-use bullets.
-
-Always start each list item with a capital letter. If the list items are short,
-incomplete sentences, do not end each item with punctuation. However, if any of
-the list items are a longer phrase with more than one full sentence, finish all
-list items with a period.
-
-
-
-```txt
-1. Use numbers
-1. If the order of the steps
-1. Is important
-
-* Otherwise
-* Use
-* Bullets
-```
-
-
-
-## Processes and procedures
-
-We use processes and procedures to provide readers with numbered steps to
-achieve a specific goal.
-
-Processes contain procedures. If the task you are describing is very lengthy, or
-has a series of distinct components, break it up into a series of procedures
-within a process.
-
-Procedures contain these elements:
-
-
-
-1. Level two section title in simple verb form
-1. Short introduction
-1. Open `` tag
-1. Level three procedure title in gerund verb form
-1. Numbered steps
-1. Screenshot
-1. Close `` tag
-
-
-
-For example:
-
-```txt
-## Install Timescale
-
-This section describes how to install Timescale on premise.
-
-
-
-### Installing Timescale
-
-1. Start each step with a verb, or a location.
-1. For example, "Run the `example` command", or "At the command prompt, open the
- `example` file."
-
-
-
-
-
-```
-
-In general, do not use result statements. However, if you feel it is absolutely
-necessary, include it immediately before the closing procedure tag, and do not
-put it as a step.
-
-## Code blocks
-
-Offset code blocks from the surrounding text by using three backticks and
-declaring the language in use in the block. Usually, this is either `sql`, for
-queries, or `bash`, for commands given at the command prompt. For a full list of
-available languages see [the prismjs site][prismjs].
-
-Make sure that the code block is indented at the same level as the surrounding text.
-
-When writing commands in a code block, do not use `#`, `$`, or any other prompt.
-Additionally, for Linux commands, do not use `sudo`, instead, use the stem
-sentence to indicate that the command must be run as the root user.
-
-For example, a bash command:
-
-```txt
-
- At the command prompt, as root, use this command:
-
- ```bash
- apt install postgresql
- ```
-
-```
-
-For example, an SQL query:
-
-```txt
-
- At the `psql` prompt, use this query:
-
- ```sql
- SELECT * FROM table LIMIT 5;
- ```
-
-```
-
-## Verbs
-
-* `Click` a button in a graphical user interface using a mouse. Do not `Click on`.
-* `Press` a key or key combination on a keyboard.
-* `Type` words or numbers using a keyboard.
-* `Check` or `uncheck` a checkbox.
-* `Select` or `deselect` an item in a menu.
-* `Navigate` to a page or location in a graphical user interface.
-
-## Word usage
-
-### A
-
-*Above*
-: Avoid all directional words. You cannot guarantee that things will stay in the
-same position, or be in the position you expect on an individual reader's
-device.
-
-*Adverbs*
-: Do not use.
-
-❌ Simply install Timescale.
-
-👍 Install Timescale.
-
-*AWS*
-: Amazon Web Services. No need to expand this acronym.
-
-*And/Or*
-: Do not use. You can usually pick one. If you're not sure, pick "and."
-
-❌ I like apples and/or oranges.
-
-👍 I like apples and oranges.
-
-*Appears*
-: Do not use.
-
-### B
-
-*Bare metal*
-: Noun.
-
-❌ "Perform a bare metal installation."
-
-👍 "Install Timescale on bare metal."
-
-*Bare-metal*
-: Adjective.
-
-❌ "Install Timescale on bare-metal."
-
-👍 "Perform a bare-metal installation."
-
-*Backend*
-: One word.
-
-*Below*
-: Avoid all directional words. You cannot guarantee that things will stay in the
-same position, or be in the position you expect on an individual reader's
-device.
-
-### C
-
-*Contractions*
-: Absolutely fine to use, but try not to overdo it.
-
-*Cybersecurity*
-: One word.
-
-### D
-
-*Dataset*
-: One word.
-
-❌ "Ingest the example data set."
-
-👍 "Ingest the example dataset."
-
-### E
-
-### F
-
-*Fail over*
-: Use as a verb
-
-*Failover*
-: Use as a noun or adjective.
-
-*File system*
-: Two words.
-
-*Frontend*
-: One word.
-
-### G
-
-*GCP*
-: Google Cloud Platform. No need to expand this acronym.
-
-### H
-
-*Hypershift*
-: One word, always capitalized. Check the spelling of this word
-carefully before publishing.
-
-### I
-
-### J
-
-### K
-
-### L
-
-*Latin abbreviations*
-: Do not use.
-
-❌ eg
-
-👍 For example
-
-❌ I.E:
-
-👍 That is,
-
-*Log in*
-: Verb.
-
-❌ "Enter your log in information."
-
-👍 "Log in to Timescale."
-
-*Login*
-: Adjective or noun.
-
-❌ "Login to Timescale."
-
-👍 "Enter your login information."
-
-### M
-
-*Managed Service for TimescaleDB*
-: The name of the product. Always capitalize the initial letters. Do not
-abbreviate.
-
-❌ "I am using Managed Service for Timescale to manage my time-series data."
-
-❌ "I am using Managed Service to manage my time-series data."
-
-👍 "I am using Managed Service for TimescaleDB to manage my time-series
-data."
-
-*Master/Slave*
-: Do not use. Use "Primary" and "Secondary" instead.
-
-*MST*
-: Do not use. Use "Managed Service for TimescaleDB" instead.
-
-### N
-
-*Next*
-: Avoid all directional words. You cannot guarantee that things will stay in the
-same position, or be in the position you expect on an individual reader's
-device.
-
-### O
-
-*Once*
-: Do not use. Use "when" instead.
-
-❌ "Once you have finished the installation, you can..."
-
-👍 "When you have finished the installation, you can."
-
-### P
-
-*Postgres*
-: Do not use. Use "PostgreSQL" instead.
-
-❌ "Run the Postgres query"
-
-👍 "Run the PostgreSQL query."
-
-*PostgreSQL*
-: Always refer to PostgreSQL by its full name and with correct capitalization,
-as shown.
-
-*Previous*
-: Avoid all directional words. You cannot guarantee that things will stay in the
-same position, or be in the position you expect on an individual reader's
-device.
-
-### Q
-
-### R
-
-### S
-
-*Simply*
-: Don't use.
-
-❌ Simply install Timescale.
-
-👍 Install Timescale.
-
-*Superuser*
-: One word.
-
-### T
-
-*Thus*
-: Do not use.
-
-*Timescale*
-: The name of the company, and the name of the product in a general
-sense. Do not use camel case.
-
-❌ TimeScale
-
-👍 Timescale is hosting a virtual event.
-
-👍 I have installed Timescale to manage my time-series data.
-
-*Timescale*
-: The name of the product. Always capitalize the initial letters.
-
-❌ "I am using timescale to manage my time-series data."
-
-❌ "I am using Timescale Cloud to manage my time-series data."
-
-👍 "I am using Timescale to manage my time-series data."
-
-*TimescaleDB*
-: The name of the PostgreSQL extension. Always capitalize the initial letter and
-the DB at the end if using in prose. If referring directly to the name of the
-extension, use all lowercase.
-
-❌ "I installed timescaleDB to manage my time-series data."
-
-👍 "I installed the `timescaledb` extension to manage my time-series data."
-
-👍 "I installed TimescaleDB to manage my time-series data."
-
-*tobs*
-: The observability suite. Do not use capitalization, even when it begins
-a sentence. If possible, rewrite the sentence to avoid this.
-
-❌ "Tobs can be used to install."
-
-👍 "Install using tobs"
-
-*TSDB*
-: Do not use. Use "Timescale database" instead.
-
-### U
-
-*Update*
-: An update is a small or minor improvement, often delivered in a patch. Updates
-are done frequently, and require little or no downtime.
-
-👍 Install the security update to patch this version.
-
-*Upgrade*
-: An upgrade is a large or major improvement, and usually requires a new
-version. Upgrades are done less frequently, and could require planning,
-prepatory backups, and planned downtime.
-
-👍 Upgrade from TimescaleDB 1 to TimescaleDB 2.
-
-👍 Upgrade from TimescaleDB 2.3 to TimescaleDB 2.4.
-
-*Utilize*
-: Do not use. Use "use" instead.
-
-### V
-
-*Vanilla PostgreSQL*
-: Do not use. If you want to differentiate between regular PostgreSQL tables,
-and tables that contain time-series, use "standard PostgreSQL".
-
-❌ "You can also create services that run vanilla PostgreSQL."
-
-👍 "You can also create services that run standard PostgreSQL."
-
-*Via*
-: Do not use. There is usually a more accurate English word, like
-"through," "with," or "using."
-
-### W
-
-*Will*
-: Do not use. It usually indicates that you are writing in future tense.
-Always write in simple present tense.
-
-❌ After installation, you will see a message.
-
-👍 After installation, you see a message.
-
-### X
-
-### Y
-
-### Z
-
-[contributors]: https://github.com/timescale/docs/blob/latest/CONTRIBUTING.md
-[github-docs]: https://github.com/timescale/docs
-[google-style]: https://developers.google.com/style
-[readme]: https://github.com/timescale/docs#readme
-[prismjs]: https://prismjs.com/#supported-languages
diff --git a/about/contribute-to-timescale.md b/about/contribute-to-timescale.md
index f16c551331..028bea5601 100644
--- a/about/contribute-to-timescale.md
+++ b/about/contribute-to-timescale.md
@@ -6,57 +6,35 @@ keywords: [contribute]
tags: [github]
---
-# Contributing to Timescale
+# Contribute to $COMPANY
-There are multiple ways to help make TimescaleDB better. All of the documentation
-and source for the PostgreSQL extension are available to use and review on
-GitHub.
+$TIMESCALE_DB, pgai, pgvectorscale, TimescaleDB Toolkit, and the $COMPANY documentation are all open source. They are available in GitHub for you use, review, and update. This page shows you where you can add to $COMPANY products.
-## Contributing to Timescale documentation
+## Contribute to the code for $COMPANY products
-Timescale documentation is hosted in a [GitHub repository][github-docs]
-and is open for contribution from all community members. If you
-find errors or would like to add content to the docs, this tutorial
-walks you through the process.
+$COMPANY appreciates any help the community can provide to make its products better! You can:
-### Making minor changes
+* Open an issue with a bug report, build issue, feature request or suggestion.
+* Fork a corresponding repository and submit a pull request.
-If you want to make only minor changes to docs, you can make corrections
-and submit pull requests on the GitHub website. Go to the file you want to
-correct and click the 'pencil' icon to edit. Once done, GitHub gives you
-an option to submit a pull request at the bottom of the page.
+Head over to the $COMPANY source repositories to learn, review, and help improve our products!
-### Making larger contributions to docs
+* [TimescaleDB][timescaledb]: a PostgreSQL extension for high-performance real-time analytics on time-series and event data.
+* [pgai][pgai]: a suite of tools to develop RAG, semantic search, and other AI applications more easily with PostgreSQL.
+* [pgvectorscale][pgvectorscale]: a complement to pgvector for higher performance embedding search and cost-efficient storage for AI applications.
+* [TimescaleDB Toolkit][toolkit]: all things analytics when using $TIMESCALE_DB, with a particular focus on developer ergonomics and performance.
-In order to modify documentation, you should have a working knowledge
-of [git][install-git] and [Markdown][markdown-tutorial]. You
-also need to create a GitHub account.
+## Contribute to $COMPANY documentation
-Be sure to read the [Timescale docs contribution styleguide][timescale-docs-style].
-You'll see information about how we refer to aspects of Timescale,
-how we format our docs, and special Markdown tags available to
-you as you author your contribution.
+$COMPANY documentation is hosted in the [docs GitHub repository][github-docs]
+and open for contribution from all community members.
-Before we accept any contributions, Timescale contributors need to
-sign the Contributor License Agreement (CLA). By signing a CLA, we
-can ensure that the community is free and confident in its
-ability to use your contributions. You are prompted to sign the
-CLA during the pull request process.
-
-## Contributing to TimescaleDB code
-
-Timescale appreciates any help the community can provide to make TimescaleDB better!
-
-There are multiple ways you can help:
-
-* Open an issue with a bug report, build issue, feature request, suggestion, etc.
-* Fork this repository and submit a pull request
-
-[Head over to our GitHub repository][github-timescaledb] for TimescaleDB to learn
-more about how you can help and to review our coding style guide!
+See the [contribution guide][contribution-guide] for details.
+[contribution-guide]: https://github.com/timescale/docs/blob/latest/CONTRIBUTING.md
[github-docs]: https://github.com/timescale/docs
-[github-timescaledb]: https://github.com/timescale/timescaledb/blob/master/CONTRIBUTING.md
-[install-git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
-[markdown-tutorial]: https://www.markdownguide.org/basic-syntax/
-[timescale-docs-style]: https://github.com/timescale/docs/blob/master/README.md
+[timescaledb]: https://github.com/timescale/timescaledb/blob/main/CONTRIBUTING.md
+[pgai]: https://github.com/timescale/pgai/blob/main/CONTRIBUTING.md
+[pgvectorscale]: https://github.com/timescale/pgvectorscale/blob/main/CONTRIBUTING.md
+[toolkit]: https://github.com/timescale/timescaledb-toolkit
+
diff --git a/about/page-index/page-index.js b/about/page-index/page-index.js
index 56d53008db..ea733dbc35 100644
--- a/about/page-index/page-index.js
+++ b/about/page-index/page-index.js
@@ -31,12 +31,7 @@ module.exports = [
title: "Contribute to Timescale",
href: "contribute-to-timescale",
excerpt: "Contribute to the Timescale codebase",
- },
- {
- title: "Contribute to Timescale documentation",
- href: "contribute-to-docs",
- excerpt: "Contribute to Timescale documentation",
- },
+ }
],
},
];
diff --git a/lambda/redirects.js b/lambda/redirects.js
index 3393be2af9..9b9d9bfdb1 100644
--- a/lambda/redirects.js
+++ b/lambda/redirects.js
@@ -372,7 +372,7 @@ module.exports = [
},
{
from: "/timescaledb/latest/contribute-to-docs",
- to: "https://docs.timescale.com/about/latest/contribute-to-docs/",
+ to: "https://docs.timescale.com/about/latest/contribute-to-timescale/",
},
{
from: "/timescaledb/latest/contribute-to-timescaledb",
diff --git a/use-timescale/alerting.md b/use-timescale/alerting.md
index 1f711d6061..837dd69511 100644
--- a/use-timescale/alerting.md
+++ b/use-timescale/alerting.md
@@ -33,7 +33,9 @@ it is designed to take advantage of the database's time-series capabilities.
From there, proceed to your dashboard and set up alert rules as described above.
+
Alerting is only available in Grafana v4.0 and later.
+
## Other alerting tools
diff --git a/use-timescale/compression/decompress-chunks.md b/use-timescale/compression/decompress-chunks.md
index 6a5dff47a1..67deb8951a 100644
--- a/use-timescale/compression/decompress-chunks.md
+++ b/use-timescale/compression/decompress-chunks.md
@@ -15,10 +15,12 @@ compressed chunk is more computationally expensive than inserting data into an
uncompressed chunk. This adds up over a lot of rows.
+
When compressing your data, you can reduce the amount of storage space for your
Timescale instance. But you should always leave some additional storage
capacity. This gives you the flexibility to decompress chunks when necessary,
for actions such as bulk inserts.
+
This section describes commands to use for decompressing chunks. You can filter