feat: improve content and heading in the guide develop a plugin pages

packages/contracts/docs/modules/ROOT/pages/guide-develop-plugin/design-your-plugin.adoc

@@ -1,12 +1,12 @@
 = Designing your plugin
 
-== Governance Plugins
+This guide explains how to design plugins for Aragon OSx, covering governance plugins, membership management, and upgradeability patterns. You'll learn about the core interfaces, implementation patterns, and how to choose the right base contract for your specific use case.
 
-### How to Build a Governance Plugin
+== Governance Plugins
 
 One of the most common use cases for plugins are governance plugins. Governance plugins are plugins DAOs install to help them make decisions.
 
-#### What are Governance Plugins
+=== What are Governance Plugins
 
 Governance plugins are characterized by the **ability to execute actions in the DAO** they have been installed to. Accordingly, the `EXECUTE_PERMISSION_ID` is granted on installation on the installing DAO to the governance plugin contract.
 
@@ -23,7 +23,7 @@ Beyond this fundamental ability, governance plugins usually implement two interf
 - xref:guide-develop-plugin/design-your-plugin#proposals[The `IProposal` interface] introducing the **notion of proposals** and how they are created and executed.
 - xref:guide-develop-plugin/design-your-plugin#membership[The `IMembership` interface] introducing the **notion of membership** to the DAO.
 
-#### Examples of Governance Plugins
+=== Examples of Governance Plugins
 
 Some examples of governance plugins are:
 
@@ -36,11 +36,7 @@ Some examples of governance plugins are:
 
 // <!-- Add a code example -->
 
-
-
-### Proposals
-
-#### The `IProposal` Interface
+=== The `IProposal` Interface
 
 The `IProposal` interface is used to create and execute proposals containing actions and a description.
 
@@ -78,7 +74,7 @@ interface IProposal {
 
 This interface contains two events and one function
 
-##### `ProposalCreated` event
+==== `ProposalCreated` event
 
 This event should be emitted when a proposal is created. It contains the following parameters:
 
@@ -90,15 +86,15 @@ This event should be emitted when a proposal is created. It contains the followi
 - `actions`: The actions that will be executed if the proposal passes.
 - `allowFailureMap`: A bitmap allowing the proposal to succeed, even if individual actions might revert. If the bit at index `i` is 1, the proposal succeeds even if the `i`th action reverts. A failure map value of 0 requires every action to not revert.
 
-##### `ProposalExecuted` event
+==== `ProposalExecuted` event
 
 This event should be emitted when a proposal is executed. It contains the proposal ID as a parameter.
 
-##### `proposalCount` function
+==== `proposalCount` function
 
 This function should return the proposal count determining the next proposal ID.
 
-#### Usage
+==== Usage
 
 ```solidity
 contract MyPlugin is IProposal {
@@ -134,9 +130,9 @@ contract MyPlugin is IProposal {
 }
 ```
 
-### Membership
 
-#### The `IMembership` Interface
+
+=== The `IMembership` Interface
 
 The `IMembership` interface defines common functions and events for for plugins that keep track of membership in a DAO. This plugins can be used to define who can vote on proposals, who can create proposals, etc. The list of members can be defined in the plugin itself or by a contract that defines the membership like an ERC20 or ERC721 token.
 
@@ -167,25 +163,25 @@ interface IMembership {
 
 The interface contains three events and one function.
 
-##### `MembersAdded` event
+==== `MembersAdded` event
 
 The members added event should be emitted when members are added to the DAO plugin. It only contains one `address[] members` parameter that references the list of new members being added.
 
 - `members`: The list of new members being added.
 
-##### `MembersRemoved` event
+==== `MembersRemoved` event
 
 The members added event should be emitted when members are removed from the DAO plugin. It only contains one `address[] members` parameter that references the list of members being removed.
 
-##### `MembershipContractAnnounced` event
+==== `MembershipContractAnnounced` event
 
 This event should be emitted during the initialization of the membership plugin to announce the membership being defined by a contract. It contains the defining contract as a parameter.
 
-##### `isMember` function
+==== `isMember` function
 
 This is a simple function that should be implemented in the plugin contract that introduces the members to the DAO. It checks if an account is a member of the DAO and returns a boolean value.
 
-#### Usage
+==== Usage
 
 ```solidity
 
@@ -222,7 +218,7 @@ contract MyPlugin is IMembership {
 
 == Choosing the Plugin Upgradeability
 
-### How to Choose the Base Contract for Your Plugin
+=== How to Choose your Plugin Upgradeability
 
 Although it is not mandatory to choose one of our interfaces as the base contracts for your plugins, we do offer some options for you to inherit from and speed up development.
 
@@ -240,7 +236,7 @@ In this regard, we provide 3 options for base contracts you can choose from:
 
 Let's take a look at what this means for you.
 
-### Upgradeability & Deployment
+=== Upgradeability & Deployment
 
 Upgradeability and the deployment method of a plugin contract go hand in hand. The motivation behind upgrading smart contracts is nicely summarized by OpenZeppelin:
 
@@ -272,10 +268,10 @@ Some key things to keep in mind:
 | |`new` Instantiation | Minimal Proxy (Clones)| Transparent Proxy| UUPS Proxy
 
 | upgradeability 
-|no  
+| [.no-cell]#no#
 | no       
-| yes     
 | yes  
+| yes
 | gas costs      
 | high 
 | very low 
@@ -292,10 +288,10 @@ Accordingly, we recommend to use link:https://eips.ethereum.org/EIPS/eip-1167[mi
 To help you with developing and deploying your plugin within the Aragon infrastructure, we provide the following implementation that you can inherit from:
 
 - `Plugin` for instantiation via `new`
-- `PluginClones` for [minimal proxy pattern link:https://eips.ethereum.org/EIPS/eip-1167[ERC-1167]] deployment
-- `PluginUUPSUpgradeable` for [UUPS pattern link:https://eips.ethereum.org/EIPS/eip-1822[ERC-1822]] deployment
+- `PluginClones` for link:https://eips.ethereum.org/EIPS/eip-1167[minimal proxy pattern ERC-1167] deployment
+- `PluginUUPSUpgradeable` for link:https://eips.ethereum.org/EIPS/eip-1822[UUPS pattern ERC-1822] deployment
 
-#### Caveats of Non-upgradeable Plugins
+=== Caveats of Non-upgradeable Plugins
 
 Aragon plugins using the non-upgradeable smart contracts bases (`Plugin`, `PluginCloneable`) can be cheap to deploy (i.e., using clones) but **cannot be updated**.
 

packages/contracts/docs/modules/ROOT/pages/guide-develop-plugin/follow-best-practices.adoc

@@ -2,7 +2,7 @@
 
 == Advice for Developing a Plugin
 
-### DOs 👌
+=== DOs 👌
 
 - Document your contracts using link:https://docs.soliditylang.org/en/v0.8.17/natspec-format.html[NatSpec].
 - Test your contracts, e.g., using toolkits such as link:https://hardhat.org/hardhat-runner/docs/guides/test-contracts[hardhat (JS)] or link:https://book.getfoundry.sh/forge/tests[Foundry (Rust)].
@@ -12,7 +12,7 @@
 - Plan the lifecycle of your plugin (need for upgrades).
 - Follow our xref:guide-develop-plugin/publishing-plugin.adoc#how_to_add_a_new_version_of_your_plugin[versioning guidelines].
 
-### DON'Ts ✋
+=== DON'Ts ✋
 
 - Leave any contract uninitialized.
 - Grant the `ROOT_PERMISSION_ID` permission to anything or anyone.

packages/contracts/docs/modules/ROOT/pages/guide-develop-plugin/index.adoc

@@ -1,12 +1,10 @@
 = How to build a DAO Plugin
 
-== Plugin Development Quickstart Guide
-
 Plugins are how we extend the functionality for DAOs. In Aragon OSx, everything a DAO can do is based on Plugin functionality enabled through permissions.
 
 In this Quickstart guide, we will use the Aragon Hardhat template to set up a plugin.
 
-## Setting up your environment
+== Setting up your environment
 
 We recommend using our link:https://github.com/aragon/osx-plugin-template-hardhat[hardhat template] to get started. If you don't have
 it installed, you can do so by running:
@@ -61,10 +59,10 @@ For more information on how to develop a plugin, you can check our plugin develo
 - xref:guide-develop-plugin/write-plugin-setup-contract.adoc[Writing your plugin setup contract]
 - xref:guide-develop-plugin/write-upgradeable-plugin.adoc[Writing upgradeable plugin]
 - xref:guide-develop-plugin/upgrade-plugin.adoc[Upgrading your plugin]
-- xref:guide-develop-plugin/follow-best-practices.adoc[Best practices and patterns]
+- xref:guide-develop-plugin/follow-best-practices.adoc[Following best practices]
 - xref:guide-develop-plugin/publishing-plugin.adoc[Publishing your plugin]
 
 
 
-IMPORTANT: This plugin template uses version TODO:GIORGI `1.4.0-alpha.5` of the Aragon OSx protocol. This version is still in development and 
+IMPORTANT: This plugin template uses version `1.4.0-alpha.5` of the Aragon OSx protocol. This version is still in development and 
 is not audited yet.

packages/contracts/docs/modules/ROOT/pages/guide-develop-plugin/publishing-plugin.adoc

@@ -1,16 +1,18 @@
 = Publication of your Plugin into Aragon OSx
 
-== How to publish a plugin into Aragon's plugin registry
-
 Once you've deployed your Plugin Setup contract, you will be able to publish your plugin into Aragon's plugin registry so any 
 Aragon DAO can install it.
 
-### 1. Make sure your plugin is deployed in the right network
+== How to publish new plugin
+
+Publishing a plugin to Aragon OSx involves a few key steps to ensure your plugin is properly registered and accessible to DAOs.
+
+=== Make sure your plugin is deployed in a supported network
 
 Make sure your Plugin Setup contract is deployed in your network of choice (you can find all of the networks we support link:https://github.com/aragon/osx-commons/tree/develop/configs/src/deployments/json[here]). 
 You will need the address of your Plugin Setup contract to be able to publish the plugin into the protocol.
 
-### 2. Publishing your plugin
+=== Publishing your plugin
 
 Every plugin in Aragon can have future versions, so when publishing a plugin to the Aragon protocol, we're really creating a link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/plugin/repo/PluginRepo.sol[PluginRepo] instance for each plugin,
 which will contain all of the plugin's versions.
@@ -24,14 +26,13 @@ You can find all of the addresses of `PluginRepoFactory` contracts by network li
 To create more versions of your plugin in the future, you'll call on the link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/plugin/repo/PluginRepo.sol#L128[createVersion function] 
 from the `PluginRepo` instance of your plugin. When you publish your plugin, you'll be able to find the address of your plugin's `PluginRepo` instance within the transaction data.
 
-### 3. Publishing subsequent builds
+=== Publishing subsequent builds
 
 When publishing subsequent builds, you want to use the `createVersion` function in the `PluginRepo` contract (link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/plugin/repo/PluginRepo.sol#L132[check out the function's source code here]).
 
 To deploy your plugin, follow the steps in the link:https://github.com/aragon/osx-plugin-template-hardhat/blob/main/README.md#deployment[osx-plugin-template-hardhat README.md].
 
 
-
 == How to add a new version of your plugin
 
 The Aragon OSx protocol has an on-chain versioning system built-in, which distinguishes between releases and builds.
@@ -94,7 +95,7 @@ Currently, two kinds of metadata exist:
 1. Release metadata
 2. Build metadata
 
-### Release Metadata
+=== Release Metadata
 
 The release metadata is a `.json` file stored on IPFS with its IPFS CID published for each release in the xref:framework/plugin-repos.adoc[PluginRepo](see also the section about xref:#how_to_add_a_new_version_of_your_plugin[versioning]).
 
@@ -123,7 +124,7 @@ The `release-metadata.json` file consists of the following entries:
 |===
 
 
-#### Example
+==== Example
 
 ```json
 {
@@ -133,7 +134,7 @@ The `release-metadata.json` file consists of the following entries:
 }
 ```
 
-### Build Metadata
+=== Build Metadata
 
 The build metadata is a `.json` file stored on IPFS with its IPFS CID published for each build **only once** 
 in the xref:framework/plugin-repos.adoc[PluginRepo] (see also the section about xref:#how_to_add_a_new_version_of_your_plugin[versioning]).
@@ -184,7 +185,7 @@ Each `"prepare..."` object contains:
 
 By following the Solidity JSON ABI format for the inputs, we followed an established standard, have support for complex types (tuples, arrays, nested versions of the prior) and allow for future extensibility (such as the human readable description texts that we have added).
 
-#### Example
+==== Example
 
 ```json
 {
@@ -234,7 +235,4 @@ By following the Solidity JSON ABI format for the inputs, we followed an establi
     }
   }
 }
-```
-
-
-// TODO merge this sections and clean up redundancy, consider also framework and core sections.
+```