DOC-491 | How to choose the right graph type (#258)

* how to choose the right graph type

* moved content into First Steps page

* Fix headline level

* Simply ToC CSS, account for level 5 and 6

* remove one level of nesting

---------

Co-authored-by: Simran Spiller <[email protected]>

Author: nerpaula

site/content/3.10/graphs/first-steps.md

@@ -172,6 +172,9 @@ The following types of named graphs exist:
 - [EnterpriseGraphs](enterprisegraphs/_index.md)
 - [SatelliteGraphs](satellitegraphs/_index.md)
 
+Selecting the optimal type of named graph in ArangoDB can help you achieve
+the best performance and scalability for your data-intensive applications.
+
 Which collections are used within a named graph is defined via 
 **edge definitions**. They describe which edge collections connect which
 vertex collections. This is defined separately for the *from* and the *to*
@@ -210,6 +213,61 @@ You can create and manage named graphs in the following ways:
   JavaScript API (see the above links of the named graph types)
 - Using the [Gharial HTTP API](../develop/http/graphs/named-graphs.md)
 
+#### When to use General Graphs
+
+The General Graph is the basic graph type in ArangoDB, suitable for small-scale
+graph use cases. Data in this type is randomly distributed across all configured
+machines, making it easy to set up. However, this approach may result in
+suboptimal query performance due to random data distribution.
+
+{{< tip >}}
+General graphs are the easiest way to get started, no special configuration required.
+{{< /tip >}}
+
+![General Graph Random Distribution](../../images/general-graph-distribution.png)
+
+#### When to use SmartGraphs
+
+The SmartGraphs further optimize data distribution by allowing you to define a
+property called `smartGraphAttribute`. This property leverages your application's
+knowledge about the graph's interconnected communities to improve data
+organization and query performance.
+
+{{< tip >}}
+For the best query performance, especially in highly interconnected graph
+scenarios, use SmartGraphs. Organize your data efficiently using the
+`smartGraphAttribute`.
+{{< /tip >}}
+
+![SmartGraph Distribution](../../images/smartgraph-distribution.png)
+
+#### When to use EnterpriseGraphs
+
+The EnterpriseGraphs are designed for large-scale graph use cases in enterprise
+environments. While data is also randomly sharded, this graph type ensures that
+all edges adjacent to a vertex are co-located on the same server. This
+optimization significantly improves query performance by reducing network hops.
+
+{{< tip >}}
+If you need improved query execution without manual data distribution, consider
+using EnterpriseGraphs.
+{{< /tip >}}
+
+![EnterpriseGraph Distribution](../../images/enterprisegraph-distribution.png)
+
+#### When to use SatelliteGraphs
+
+SatelliteGraphs replicate one or more graphs to all machines within a cluster
+so queries can be executed locally. All vertices and edges are available on
+every node for maximum data locality, therefore no network hops are required
+to traverse the graph.
+
+{{< tip >}}
+When using SatelliteGraphs, expect slower write performance because the data is
+replicated across DB-Servers. For a more efficient option that doesn't replicate
+all graph data to every server in your cluster, consider SmartGraphs.
+{{< /tip >}}
+
 ### Anonymous graphs
 
 An anonymous graph is the graph that your data implicitly defines by edges that

site/content/3.11/graphs/first-steps.md

@@ -172,6 +172,9 @@ The following types of named graphs exist:
 - [EnterpriseGraphs](enterprisegraphs/_index.md)
 - [SatelliteGraphs](satellitegraphs/_index.md)
 
+Selecting the optimal type of named graph in ArangoDB can help you achieve
+the best performance and scalability for your data-intensive applications.
+
 Which collections are used within a named graph is defined via 
 **edge definitions**. They describe which edge collections connect which
 vertex collections. This is defined separately for the *from* and the *to*
@@ -210,6 +213,61 @@ You can create and manage named graphs in the following ways:
   JavaScript API (see the above links of the named graph types)
 - Using the [Gharial HTTP API](../develop/http/graphs/named-graphs.md)
 
+#### When to use General Graphs
+
+The General Graph is the basic graph type in ArangoDB, suitable for small-scale
+graph use cases. Data in this type is randomly distributed across all configured
+machines, making it easy to set up. However, this approach may result in
+suboptimal query performance due to random data distribution.
+
+{{< tip >}}
+General graphs are the easiest way to get started, no special configuration required.
+{{< /tip >}}
+
+![General Graph Random Distribution](../../images/general-graph-distribution.png)
+
+#### When to use SmartGraphs
+
+The SmartGraphs further optimize data distribution by allowing you to define a
+property called `smartGraphAttribute`. This property leverages your application's
+knowledge about the graph's interconnected communities to improve data
+organization and query performance.
+
+{{< tip >}}
+For the best query performance, especially in highly interconnected graph
+scenarios, use SmartGraphs. Organize your data efficiently using the
+`smartGraphAttribute`.
+{{< /tip >}}
+
+![SmartGraph Distribution](../../images/smartgraph-distribution.png)
+
+#### When to use EnterpriseGraphs
+
+The EnterpriseGraphs are designed for large-scale graph use cases in enterprise
+environments. While data is also randomly sharded, this graph type ensures that
+all edges adjacent to a vertex are co-located on the same server. This
+optimization significantly improves query performance by reducing network hops.
+
+{{< tip >}}
+If you need improved query execution without manual data distribution, consider
+using EnterpriseGraphs.
+{{< /tip >}}
+
+![EnterpriseGraph Distribution](../../images/enterprisegraph-distribution.png)
+
+#### When to use SatelliteGraphs
+
+SatelliteGraphs replicate one or more graphs to all machines within a cluster
+so queries can be executed locally. All vertices and edges are available on
+every node for maximum data locality, therefore no network hops are required
+to traverse the graph.
+
+{{< tip >}}
+When using SatelliteGraphs, expect slower write performance because the data is
+replicated across DB-Servers. For a more efficient option that doesn't replicate
+all graph data to every server in your cluster, consider SmartGraphs.
+{{< /tip >}}
+
 ### Anonymous graphs
 
 An anonymous graph is the graph that your data implicitly defines by edges that

site/content/3.12/graphs/first-steps.md

@@ -172,6 +172,9 @@ The following types of named graphs exist:
 - [EnterpriseGraphs](enterprisegraphs/_index.md)
 - [SatelliteGraphs](satellitegraphs/_index.md)
 
+Selecting the optimal type of named graph in ArangoDB can help you achieve
+the best performance and scalability for your data-intensive applications.
+
 Which collections are used within a named graph is defined via 
 **edge definitions**. They describe which edge collections connect which
 vertex collections. This is defined separately for the *from* and the *to*
@@ -210,6 +213,61 @@ You can create and manage named graphs in the following ways:
   JavaScript API (see the above links of the named graph types)
 - Using the [Gharial HTTP API](../develop/http/graphs/named-graphs.md)
 
+#### When to use General Graphs
+
+The General Graph is the basic graph type in ArangoDB, suitable for small-scale
+graph use cases. Data in this type is randomly distributed across all configured
+machines, making it easy to set up. However, this approach may result in
+suboptimal query performance due to random data distribution.
+
+{{< tip >}}
+General graphs are the easiest way to get started, no special configuration required.
+{{< /tip >}}
+
+![General Graph Random Distribution](../../images/general-graph-distribution.png)
+
+#### When to use SmartGraphs
+
+The SmartGraphs further optimize data distribution by allowing you to define a
+property called `smartGraphAttribute`. This property leverages your application's
+knowledge about the graph's interconnected communities to improve data
+organization and query performance.
+
+{{< tip >}}
+For the best query performance, especially in highly interconnected graph
+scenarios, use SmartGraphs. Organize your data efficiently using the
+`smartGraphAttribute`.
+{{< /tip >}}
+
+![SmartGraph Distribution](../../images/smartgraph-distribution.png)
+
+#### When to use EnterpriseGraphs
+
+The EnterpriseGraphs are designed for large-scale graph use cases in enterprise
+environments. While data is also randomly sharded, this graph type ensures that
+all edges adjacent to a vertex are co-located on the same server. This
+optimization significantly improves query performance by reducing network hops.
+
+{{< tip >}}
+If you need improved query execution without manual data distribution, consider
+using EnterpriseGraphs.
+{{< /tip >}}
+
+![EnterpriseGraph Distribution](../../images/enterprisegraph-distribution.png)
+
+#### When to use SatelliteGraphs
+
+SatelliteGraphs replicate one or more graphs to all machines within a cluster
+so queries can be executed locally. All vertices and edges are available on
+every node for maximum data locality, therefore no network hops are required
+to traverse the graph.
+
+{{< tip >}}
+When using SatelliteGraphs, expect slower write performance because the data is
+replicated across DB-Servers. For a more efficient option that doesn't replicate
+all graph data to every server in your cluster, consider SmartGraphs.
+{{< /tip >}}
+
 ### Anonymous graphs
 
 An anonymous graph is the graph that your data implicitly defines by edges that

site/content/images/enterprisegraph-distribution.png

@@ -1170,23 +1170,21 @@ header .logo {
 }
 
 .toc-header {
-    font-size: 20px;
-    font-weight: 500;
+    font-size: 15px;
+    font-weight: 700;
+    letter-spacing: 0;
     margin-bottom: 16px;
 }
+
 .toc-header > p {
-    font-size: 15px;
     line-height: 16px;
-    font-weight: bolder;
-    letter-spacing: 0;
-    margin: 0px 0px 0px 0px;
+    margin: 0;
 }
 
 .toc-content {
     margin-bottom: 30px;
 }
 
-
 #TableOfContents {
     margin-right: 1rem;
 }
@@ -1197,43 +1195,36 @@ header .logo {
 
 #TableOfContents ul {
     list-style: none;
-    margin: 0 0 0 0;
+    margin: 0;
 }
 
 #TableOfContents a {
     display: inline-block;
-    padding: 0.25rem 0.5rem 0.25rem 0.5rem;
+    padding: 0.25rem 0.5rem;
     text-decoration: none;
     color: var(--TOC-ENTRY-COLOR);
+    font-size: 16px;
+    font-weight: 400;
 }
 
 #TableOfContents a:hover {
     border-bottom: none;
 }
 
-
-#TableOfContents .level-1 > a {
-    font-size: 16px;
-}
-
-#TableOfContents .level-2 > a {
-    font-size: 16px;
-    font-weight: 400;
-}
-
 #TableOfContents .level-3 > a {
-    padding-left: 1em;
-    font-size: 16px;
-    font-weight: 400;
+    padding-left: 1.25rem;
 }
 
 #TableOfContents .level-4 > a {
-    padding-left: 2em;
-    font-size: 16px;
-    font-weight: 400;
+    padding-left: 2rem;
 }
 
-
+#TableOfContents .level-5 > a {
+    padding-left: 2.75rem;
+}
+#TableOfContents .level-6 > a {
+    padding-left: 3.5rem;
+}
 
 #TableOfContents .is-active > a {
     color: #222222;
@@ -1243,7 +1234,8 @@ header .logo {
 #TableOfContents .level-2:hover,
 #TableOfContents .level-3:hover,
 #TableOfContents .level-4:hover, 
-#TableOfContents .level-5:hover {
+#TableOfContents .level-5:hover,
+#TableOfContents .level-6:hover {
     font-weight: bold;
     --tw-bg-opacity: 0.2;
     background-color: var(--gray-100);