Concordium · dragosgd · Dec 6, 2024 · Dec 5, 2024 · Dec 5, 2024 · Dec 6, 2024
diff --git a/source/mainnet/docs/index.rst b/source/mainnet/docs/index.rst
@@ -71,12 +71,11 @@ Explore our developer resources, including detailed documentation, tutorials, an
    :caption: Smart Contracts
    :hidden:
 
+   QuickStart <smart-contracts/guides/quick-start>
    What is a smart contract? <smart-contracts/introduction>
-   QuickStart to smart contract deployment <smart-contracts/guides/quick-start>
-   Build a smart contract <smart-contracts/guides/build-contract>
-   Deploy a smart contract <smart-contracts/guides/deploy-module>
-   Development best practices <smart-contracts/guides/development>
-   Cost reduction best practices <smart-contracts/guides/costs>
+   Build <smart-contracts/guides/build-contract>
+   Deploy <smart-contracts/guides/deploy-module>
+   Best practices <smart-contracts/best-practices/index>
    References <smart-contracts/references/index>
 
 .. toctree::

diff --git a/...net/docs/smart-contracts/guides/costs.rst → .../smart-contracts/best-practices/costs.rst b/...net/docs/smart-contracts/guides/costs.rst → .../smart-contracts/best-practices/costs.rst
@@ -1,8 +1,8 @@
 .. _sc-costs-best-practices:
 
-=============================
-Cost reduction best practices
-=============================
+==============
+Cost reduction
+==============
 
 There are several ways that you can reduce transaction costs when developing your smart contracts.
 

diff --git a/...cs/smart-contracts/guides/development.rst → ...-contracts/best-practices/development.rst b/...cs/smart-contracts/guides/development.rst → ...-contracts/best-practices/development.rst
@@ -1,8 +1,8 @@
 .. _sc-development-best-practices:
 
-==========================
-Development best practices
-==========================
+===========
+Development
+===========
 
 This document provides guidelines for developing smart contracts, including best practices for smart contract development, audit, information about common pitfalls and security vulnerabilities, and how to avoid them.
 

diff --git a/source/mainnet/docs/smart-contracts/best-practices/index.rst b/source/mainnet/docs/smart-contracts/best-practices/index.rst
@@ -0,0 +1,17 @@
+.. _best-practices:
+
+==============
+Best Practices
+==============
+
+Concordium, with its unique approach to identity verification and privacy, provides a robust platform for secure and scalable smart contract development.
+However, creating efficient, reliable, and cost-effective smart contracts requires adherence to best practices that maximize performance while minimizing risks and costs.
+This following artilces in this section are dedicated to guiding developers through the best practices for building high-quality smart contracts on Concordium.
+By following these recommandations, developers can ensure their contracts are not only technically sound but also optimized for the unique features and constraints of Concordium.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   development
+   costs
diff --git a/source/mainnet/docs/smart-contracts/contract-instances.rst b/source/mainnet/docs/smart-contracts/contract-instances.rst
@@ -1,8 +1,8 @@
 .. _contract-instances:
 
-========================
-Smart contract instances
-========================
+=========
+Instances
+=========
 
 A :term:`smart contract instance<instance>` is a smart contract module together with a
 specific state and an amount of CCD tokens. A smart contract instance is often just called an *instance*.

diff --git a/source/mainnet/docs/smart-contracts/contract-lifecycle.rst b/source/mainnet/docs/smart-contracts/contract-lifecycle.rst
@@ -1,7 +1,7 @@
 .. _sc-lifecycle:
 
 ==============================
-Smart contract life cycle
+Life cycle
 ==============================
 
 A smart contract is first deployed to the chain as part of a :ref:`contract

diff --git a/source/mainnet/docs/smart-contracts/contract-module.rst b/source/mainnet/docs/smart-contracts/contract-module.rst
@@ -1,7 +1,7 @@
 .. _contract-module:
 
 ======================
-Smart contract modules
+Modules
 ======================
 
 Smart contracts are deployed on the chain in *smart contract modules*. A smart contract module is often referred to simply as a *module*.

diff --git a/source/mainnet/docs/smart-contracts/contract-schema.rst b/source/mainnet/docs/smart-contracts/contract-schema.rst
@@ -12,9 +12,9 @@
 
 .. _contract-schema:
 
-======================
-Smart contract schemas
-======================
+================
+Contract schemas
+================
 
 A smart contract schema is a description of how to represent bytes in a more
 structured representation. It can be used by external tools when displaying the

diff --git a/source/mainnet/docs/smart-contracts/develop-contracts.rst b/source/mainnet/docs/smart-contracts/develop-contracts.rst
@@ -14,9 +14,9 @@
 
 .. _writing-smart-contracts:
 
-===============================
-Develop smart contracts in Rust
-===============================
+==========
+Using Rust
+==========
 
 On the Concordium blockchain smart contracts are deployed as Wasm modules, but
 Wasm is designed primarily as a compilation target and is not convenient to
@@ -143,6 +143,10 @@ There are a number of things to notice:
                 the values are stored in the state. To load
                 the values again, the state context is needed, hence the ``DeserialWithState``.
 
+.. note::
+
+   There is also the option of building a contract using ``no_std``. For more information, read :ref:`no-std`
+
 .. _serialize-state-and-parameters:
 
 Serializable state and parameters

diff --git a/source/mainnet/docs/smart-contracts/guides/compile-module.rst b/source/mainnet/docs/smart-contracts/guides/compile-module.rst
@@ -4,9 +4,9 @@
 
 .. _compile-module:
 
-====================================
-Compile a Rust smart contract module
-====================================
+==================
+Module Compilation
+==================
 
 This guide will show you how to compile smart contract module written in Rust to
 a Wasm module.

diff --git a/source/mainnet/docs/smart-contracts/guides/custom-errors.rst b/source/mainnet/docs/smart-contracts/guides/custom-errors.rst
@@ -1,9 +1,9 @@
 .. _custom discriminant values: https://doc.rust-lang.org/reference/items/enumerations.html#custom-discriminant-values-for-fieldless-enumerations
 .. _custom-errors:
 
-====================
-Return custom errors
-====================
+=============
+Custom errors
+=============
 
 This guide shows how to return custom errors from your Rust smart contract.
 

diff --git a/source/mainnet/docs/smart-contracts/guides/factory-pattern.rst b/source/mainnet/docs/smart-contracts/guides/factory-pattern.rst
@@ -1,15 +1,8 @@
 .. _factory-pattern:
 
-=======================================
-Use the factory pattern on Concordium
-=======================================
-
-.. Warning::
-
-    This guide makes use of features that are first available in protocol version 7,
-    namely getting the contract name and module reference of a smart contract instance
-    from a smart contract.
-    Before the protocol upgrade to version 7 (expected summer 2024), these features will not work.
+===============
+Factory pattern
+===============
 
 The factory pattern is a design pattern where one contract (the factory) creates instances of
 another contract (the products). This pattern makes sense on Ethereum, where deploying a smart

diff --git a/source/mainnet/docs/smart-contracts/guides/initialize-contract.rst b/source/mainnet/docs/smart-contracts/guides/initialize-contract.rst
@@ -1,9 +1,9 @@
 .. include:: ../../../variables.rst
 .. _initialize-contract:
 
-====================================
-Initialize a smart contract instance
-====================================
+==========
+Initialize
+==========
 
 This guide will show you how to initialize a smart contract from a deployed
 smart contract module with parameters in JSON or binary format.

diff --git a/source/mainnet/docs/smart-contracts/guides/inspect-instance.rst b/source/mainnet/docs/smart-contracts/guides/inspect-instance.rst
@@ -1,8 +1,8 @@
 .. _inspect-instance:
 
-=================================
-Inspect a smart contract instance
-=================================
+=======
+Inspect
+=======
 
 This guide explains how to inspect a smart contract instance.
 Inspecting an instance shows you its name, owner, module reference, balance,

diff --git a/source/mainnet/docs/smart-contracts/guides/integration-test-contract.rst b/source/mainnet/docs/smart-contracts/guides/integration-test-contract.rst
@@ -1,8 +1,8 @@
 .. _integration-test-contract:
 
-===================================
-Integration test a contract in Rust
-===================================
+=================
+Integration tests
+=================
 
 This guide describes how to write *integration tests* in Rust for your smart contracts using the `Concordium smart contract testing library <https://docs.rs/concordium-smart-contract-testing/latest/concordium_smart_contract_testing/>`_.
 

diff --git a/source/mainnet/docs/smart-contracts/guides/interact-instance.rst b/source/mainnet/docs/smart-contracts/guides/interact-instance.rst
@@ -1,8 +1,8 @@
 .. _interact-instance:
 
-=======================================
-Interact with a smart contract instance
-=======================================
+========
+Interact
+========
 
 This guide will show you, how to interact with a smart contract instance, which
 means triggering a receive function that, possibly, updates the state of the

diff --git a/source/mainnet/docs/smart-contracts/guides/invoke-instance.rst b/source/mainnet/docs/smart-contracts/guides/invoke-instance.rst
@@ -1,8 +1,8 @@
 .. _invoke-instance:
 
-================================
-Invoke a smart contract instance
-================================
+======
+Invoke
+======
 
 This guide explains how to invoke a smart contract instance, which
 means triggering a receive function and viewing its return value. Invoking an

diff --git a/source/mainnet/docs/smart-contracts/guides/json-params.rst b/source/mainnet/docs/smart-contracts/guides/json-params.rst
@@ -1,8 +1,8 @@
 .. _json-params:
 
-=============================
-Work with the JSON parameters
-=============================
+===============
+JSON parameters
+===============
 
 This guide explains how to interact with the CIS-2 smart contract functions by providing input JSON parameters. This guide uses the `cis2-multi smart contract <https://github.com/Concordium/concordium-rust-smart-contracts/tree/main/examples/cis2-multi>`__ as a starting point, and then continues with a couple of custom input types.
 

diff --git a/source/mainnet/docs/smart-contracts/guides/no-std.rst b/source/mainnet/docs/smart-contracts/guides/no-std.rst
@@ -1,8 +1,8 @@
 .. _no-std:
 
-======================
-Build using ``no_std``
-======================
+================
+Using ``no_std``
+================
 
 This guide shows how to enable ``no_std`` for your rust smart contract,
 potentially reducing the size of the resulting Wasm module by several kilobytes.

diff --git a/source/mainnet/docs/smart-contracts/guides/setup-contract.rst b/source/mainnet/docs/smart-contracts/guides/setup-contract.rst
@@ -2,9 +2,9 @@
 
 .. _setup-contract:
 
-===============================
-Set up a smart contract project
-===============================
+================
+Set up a project
+================
 
 This guide documents two different options (*from a template* or *from scratch*) to create a new Concordium smart contract project.
 The *from a template* option is available for ``cargo-concordium`` version 2.2.0 or greater. It provides you with some

diff --git a/source/mainnet/docs/smart-contracts/guides/unit-test-contract.rst b/source/mainnet/docs/smart-contracts/guides/unit-test-contract.rst
@@ -2,9 +2,9 @@
 
 .. _unit-test-contract:
 
-============================
-Unit test a contract in Rust
-============================
+============
+Unit testing
+============
 
 .. warning::
 

diff --git a/source/mainnet/docs/smart-contracts/guides/upgradeable-contract.rst b/source/mainnet/docs/smart-contracts/guides/upgradeable-contract.rst
@@ -1,8 +1,8 @@
 .. _guide-upgradable-contract:
 
-===========================
-Make a contract upgradeable
-===========================
+====================
+Upgradeability Guide
+====================
 
 This guide shows how to make a Rust smart contract upgradeable.