chore: update the hypertable links. (#3636)

* chore: update the hypertable links.

api/create_hypertable_old.md

@@ -10,6 +10,13 @@ api:
 
 # create_hypertable() (old interface)
 
+<Highlight type="warning">
+
+This page describes the hypertable API supported prior to TimescaleDB v2.13. Best practice is to use the new 
+[`create_hypertable`][api-create-hypertable] interface.
+
+</Highlight>
+
 Creates a TimescaleDB hypertable from a PostgreSQL table (replacing the latter),
 partitioned on time and with the option to partition on one or more other
 columns. The PostgreSQL table cannot be an already partitioned table
@@ -183,3 +190,4 @@ SELECT create_hypertable('events', 'event', time_partitioning_func => 'event_sta
 [create_distributed_hypertable]: /api/:currentVersion:/distributed-hypertables/create_distributed_hypertable
 [hash-partitions]: /use-timescale/:currentVersion:/hypertables/about-hypertables/#hypertable-partitioning
 [hypertable-docs]: /use-timescale/:currentVersion:/hypertables/
+[api-create-hypertable]: /api/:currentVersion:/hypertable/create_hypertable/

use-timescale/hypertables/create.md

@@ -7,29 +7,22 @@ keywords: [hypertables, create]
 
 # Create hypertables
 
-After [creating a Timescale database][install], you're ready to create your
-first hypertable. Creating a hypertable is a two-step process:
 
-1.  Create a PostgreSQL table as usual
-1.  Convert it to a hypertable
+Hypertables are designed for real-time analytics, they are PostgreSQL tables that automatically partition your data by 
+time. Typically, you partition hypertables on columns that hold time values. These partitioning columns can be of 
+the `timestamptz`, `date`, or `integer` types. While `timestamp` is also supported, 
+[best practice is to use `timestamptz`][timestamps-best-practice].
 
-<Highlight type="note">
-This code uses the new generalized hypertable API introduced in
-TimescaleDB 2.13. The [old interface for `create_hypertable` is also
-available](/api/:currentVersion:/hypertable/create_hypertable_old/).
-</Highlight>
+This code uses the best practice [`create_hypertable`][api-create-hypertable] API introduced in TimescaleDB 2.13. 
+You can also use the [old interface](/api/:currentVersion:/hypertable/create_hypertable_old/).
 
-## Create a hypertable
 
-To create a hypertable, you create a standard PostgreSQL table and then
-convert it into a hypertable.
+## Create a hypertable
 
-Hypertables are designed for real-time analytics and typically partitioned by columns that hold time values. These can be of the `timestamptz`, `date`, or `integer` types. While `timestamp` is also supported, best practice is to use `timestamptz` instead. [PostgreSQL timestamp](https://wiki.postgresql.org/wiki/Don't_Do_This#Don.27t_use_timestamp_.28without_time_zone.29) explains why using `timestamp` is discouraged.
+After you have [created a Timescale Cloud service][install], you're ready to create your first hypertable:
 
 <Procedure>
 
-### Creating a hypertable
-
 1.  Create a standard [PostgreSQL table][postgres-createtable]:
 
     ```sql
@@ -42,27 +35,30 @@ Hypertables are designed for real-time analytics and typically partitioned by co
     );
     ```
 
-1.  Convert the table to a hypertable. Specify the name of the table you want to
-    convert, and the column that holds its time values.
+1.  [Convert the table to a hypertable][api-create-hypertable]. 
+
+    Specify the name of the table to convert and the column that holds its time values. For example:
 
      ```sql
      SELECT create_hypertable('conditions', by_range('time'));
      ```
 
 <Highlight type="note">
 
-If your table already has data, you can migrate the data when creating the
-hypertable. Set the `migrate_data` argument to true when you call the
-`create_hypertable` function. This might take a long time if you have a lot of
-data. For more information about migrating data, see the
+If your table already has data, set [`migrate_data` to `true`][api-create-hypertable-arguments] when 
+you create the hypertable.
+
+However, if you have a lot of data, this may take a long time. For more information about migrating data, see 
 [Migrate your data to Timescale Cloud][data-migration].
 
 </Highlight>
 
 </Procedure>
 
-[create-distributed-hypertable]: /self-hosted/:currentVersion:/distributed-hypertables/create-distributed-hypertables/
 [install]: /getting-started/:currentVersion:/
 [postgres-createtable]: https://www.postgresql.org/docs/current/sql-createtable.html
 [postgresql-timestamp]: https://wiki.postgresql.org/wiki/Don't_Do_This#Don.27t_use_timestamp_.28without_time_zone.29
 [data-migration]: /migrate/:currentVersion:/
+[api-create-hypertable]: /api/:currentVersion:/hypertable/create_hypertable/
+[api-create-hypertable-arguments]: /api/:currentVersion:/hypertable/create_hypertable/#arguments
+[timestamps-best-practice]: https://wiki.postgresql.org/wiki/Don't_Do_This#Don.27t_use_timestamp_.28without_time_zone.29