improve intro and api links

docs/api-reference/api-reference.md

@@ -14,7 +14,7 @@ The API-endpoint exposes all functionality to upload and download content to and
 
 Detailed information about Bee API endpoint can be found here:
 
-- <a href="/api" target="_blank" rel="noopener noreferrer">Bee API reference.</a>
+### <a href="/api" target="_blank" rel="noopener noreferrer">Bee API reference.</a>
 
 
 ## Debug API
@@ -24,7 +24,7 @@ The debug-API is disabled by default but be enabled by setting the `enable-debug
 For a new installation of Bee, the debug API endpoint is not yet exposed for security reasons. To enable the debug API endpoints, set `debug-api-enable` to `true` in your [configuration file](/docs/working-with-bee/configuration) and restart your Bee service.
 :::
 
-- <a href="/debug-api" target="_blank" rel="noopener noreferrer">Debug API reference.</a>,
+### <a href="/debug-api" target="_blank" rel="noopener noreferrer">Debug API reference.</a>
 
 :::danger 
 Your Debug API should not be exposed to the public internet, make sure that your network has a firewall which blocks port `1635`, or bind the Debug API to `localhost`

docs/introduction.md

@@ -10,16 +10,22 @@ As soon as your Bee client is up and running you will begin to connect with peer
 
 Swarm is a decentralised data storage and distribution technology, ready to power the next generation of censorship resistant, unstoppable serverless apps. It is the complement to blockchain based smart contracts originally envisaged by the Ethereum cryptocurrency and provides the mass storage piece in the Dapp building puzzle. 
 
-Swarm is economically self-sustaining due to a built-in incentive system enforced through smart contracts on the Ethereum blockchain. Swarm aspires to shape the future towards a self-sovereign global society and permissionless open markets. On Swarm, applications can run autonomously yet securely in a planetary-scale deployment and execution environment.
+Swarm is economically self-sustaining due to a built-in incentive system enforced through smart contracts on the Ethereum blockchain. Swarm aspires to shape the future towards a self-sovereign global society and permissionless open markets. Applications can run autonomously yet securely in a planetary-scale deployment and execution environment.
 
 ## Installation
 Don't have Bee installed yet? It's easy! Head over to the [installation](/docs/installation/quick-start) section to get Bee up and running.
 
-## Usage
-To learn more about how to get the most out of Bee, head over to the [working with Bee](/docs/access-the-swarm/upload-and-download) section to find out how to share files with your friends, use Bee to host a website on a public Swarm Gateway, and much more...
+## Working With Bee
+Once you have Bee installed, find out how to configure your software, interact with the API, monitor what Bee is up to, and make those all important backups in the [working with Bee](/docs/working-with-bee/introduction) section.
+
+## Access the Swarm
+To learn more about how to get the most out of Bee, find out how to [access the swarm](/docs/access-the-swarm/upload-and-download) section so you can share files with your friends, use Bee to host a website on a public Swarm Gateway, and much more!
 
+## API Reference
+[Find detailed information](/docs/api-reference/api-reference) on all the endpoints available in the autogenerated <a href="/api" target="_blank" rel="noopener noreferrer">API reference</a> and <a href="/debug-api" target="_blank" rel="noopener noreferrer">Debug API reference</a> guides.
+
 ## Dapps
-Swarm is all about dapps. We strive to provide the most developer friendly environment in which to build dapps. Built on principles of functionality, flexibility and accessibility, Bee provides high level constructs for file storage, feeds and key-value stores, while also providing the low level access with libraries that create Single Owner and Trojan chunks clientside, with total e2e privacy. Learn more about how to [develop on Swarm](/docs/dapps-on-swarm/introduction)
+Swarm is all about dapps. We strive to provide the most developer friendly environment on which to build your decentralised organisation. Built on the principles of functionality, flexibility and accessibility, Bee provides high level constructs for file storage, feeds and key-value stores, while also providing the low level access with libraries that create Single Owner and Trojan chunks clientside, with total e2e privacy. Learn more about how to [develop on Swarm](/docs/dapps-on-swarm/introduction)
 
 ## Incentives
 Need even more incentive to get involved with the wonderful world of Swarm? Find out how you'll soon be [earning gBZZ tokens](/docs/working-with-bee/cashing-out) for storing and distributing your share of the worlds data, sharing is caring!