3452 docs rfc update the contribution guide

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: `<Optional />`
 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.
+
+
+
+

_multi-code-block.md

@@ -34,4 +34,4 @@ def different_python:
 
 </tab>
 
-</Terminal>
+</Terminal>

_partials/_deprecated.md

@@ -1,5 +1,7 @@
 <Highlight type="deprecation">
+
 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/).
+
 </Highlight>

_partials/_formatting_examples.md

@@ -0,0 +1,170 @@
+# 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.  
+
+![Procedure example](https://assets.timescale.com/docs/images/procedure-syntax.png)
+
+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
+
+    ![Note highlight](https://assets.timescale.com/docs/images/highlight-note.png)
+
+    See a [use example][disable-chunk-skipping] in the docs.
+
+- Important
+
+    ![Important highlight](https://assets.timescale.com/docs/images/highlight-important.png)
+
+    See a [use example][decompress-chunks] in the docs.
+
+- Warning
+
+    ![Caution highlight](https://assets.timescale.com/docs/images/highlight-warning.png)
+
+    See a [use example][alerting] in the docs.
+
+- Deprecation
+
+    ![Deprecated highlight](https://assets.timescale.com/docs/images/highlight-deprecation.png)
+
+    See a [use example][deprecation] in the docs.
+
+- Cloud
+
+    ![Cloud highlight](https://assets.timescale.com/docs/images/highlight-cloud.png)
+
+    Syntax example:
+
+    ```text
+    <Highlight type="cloud">
+
+    A note dealing specifically with Timescale Cloud.
+
+    </Highlight>
+    ```
+
+## Tabs
+
+![Tabs](https://assets.timescale.com/docs/images/tabs-example.png)
+
+See a [use example][live-migration] in the docs.
+
+## Code blocks 
+
+As a default, use [fenced Markdown code blocks][fenced-code-blocks]:
+
+![Regular code block](https://assets.timescale.com/docs/images/markdown-code-block.png)
+
+To remove line numbers and the copy button, use the `CodeBlock` component with `canCopy` and `showLineNumbers` set to `false`:
+
+![Custom code block](https://assets.timescale.com/docs/images/custom-code-block.png)
+
+See a [use example][aggregation] in the docs.
+
+## Multi-tab code blocks
+
+![Multi-tab code block](https://assets.timescale.com/docs/images/multi-tab-code.png)
+
+Syntax example: 
+
+    <Terminal>
+
+    <tab label='ruby'>
+
+    ```ruby
+    ruby code
+    ```
+
+    </tab>
+
+    <tab label="python">
+
+    ```python
+    pyhon code
+    ```
+
+    </tab>
+
+    <tab label="go">
+
+    ```go
+    different python code
+    ```
+
+    </tab>
+
+    </Terminal>
+
+## Tags
+
+- Download
+
+  ![Download tag](https://assets.timescale.com/docs/images/tag-download.png)
+
+  See a [use example][time-series-data] in the docs.
+
+- Experimental
+
+  ![Experimental tag](https://assets.timescale.com/docs/images/tag-experimental.png)
+
+  See a [use example][time-bucket] in the docs.
+
+- Toolkit
+
+  ![Tooklit tag](https://assets.timescale.com/docs/images/tag-toolkit.png)
+
+  See a [use example][time-weighted-average] in the docs.
+
+- Community
+
+  ![Community tag](https://assets.timescale.com/docs/images/tag-community.png)
+
+  See a [use example][add-compression-policy] in the docs.
+
+- Hollow
+
+  ![Hollow tag](https://assets.timescale.com/docs/images/hollow-tag.png)
+
+  Syntax example:
+
+  ```text
+  <Tag variant="hollow">Text to display in a tag</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]
+
+See [more examples][run-queries] in the docs.
+
+[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/aggregation.md
+[time-series-data]: ../getting-started/time-series-data.md
+[time-bucket]: ../api/time_bucket_ng.md
+[time-weighted-average]: ../api/time-weighted-averages.md
+[add-compression-policy]: ../api/add_compression_policy.md
+[reference-links]: https://www.markdownguide.org/basic-syntax/#reference-style-links
+[run-queries]: ../getting-started/run-queires-from-console.md
+
+

_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')
   ```
 
-</Procedure>
+</Procedure>

about/contribute-to-timescale.md

@@ -6,57 +6,37 @@ keywords: [contribute]
 tags: [github]
 ---
 
-# Contributing to Timescale
+# Contribute to Timescale
 
-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.
+TimescaleDB, pgai, pgvectorscale, TimescaleDB Toolkit, and the Timescale documentation are all open source. They are available in GitHub for you use, review and update. This page shows you the repositories where you can add to Timescale products.
 
-## 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 the docs, this tutorial
-walks you through the process.
-
-### Making minor changes
-
-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.
-
-### Making larger contributions to docs
+## Contribute to the code for Timescale products
 
-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.
+Timescale appreciates any help the community can provide to make its products better!
 
-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.
+There are multiple ways you can help:
 
-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.
+* Open an issue with a bug report, build issue, feature request, suggestion, etc.
+* Fork this repository and submit a pull request
 
-## Contributing to TimescaleDB code
+Head over to the Timescale source repositories to learn, review, and help improve our products!
 
-Timescale appreciates any help the community can provide to make TimescaleDB better!
+* [TimescaleDB][timescaledb]: an extension for PostgreSQL that enables time-series, events, and real-time analytics workloads, while increasing ingest, query, and storage performance.
+* [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 TimescaleDB, with a particular focus on developer ergonomics and performance.
 
-There are multiple ways you can help:
+## Contributing to Timescale documentation
 
-*   Open an issue with a bug report, build issue, feature request, suggestion, etc.
-*   Fork this repository and submit a pull request
+Timescale documentation is hosted in the [docs GitHub repository][github-docs]
+and open for contribution from all community members.
 
-[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
+

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.
 
 <Highlight type="warning">
+
 Alerting is only available in Grafana v4.0 and later.
+
 </Highlight>
 
 ## Other alerting tools

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.
 
 <Highlight type="important">
+
 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.
+
 </Highlight>
 
 This section describes commands to use for decompressing chunks. You can filter