docs: comprehensive documentation improvements across Learn, Build, Operate, and Reference sections

README.md

@@ -31,4 +31,28 @@ Besides the actual content, each Space consists of:
 
 What kinds of changes are we looking for?
 
-If you see a typo, a missing guide or tutorial, an unclear explanation, or really anything else you think could improve the quality of the documentation, please feel free to open an issue or create a pull request.
+If you see a typo, a missing guide or tutorial, an unclear explanation, or really anything else you think could improve the quality of the documentation, please feel free to open an issue or create a pull request.
+
+### Contribution Guidelines
+
+When contributing, please:
+
+1. **Create a descriptive PR title** that summarizes your changes
+2. **Reference any related issues** in your PR description
+3. **Ensure markdown formatting is correct** before submitting
+4. **Keep changes focused** - one PR should address one topic
+
+### Quick Links
+
+| Resource | Link |
+| -------- | ---- |
+| Live Documentation | [docs.stacks.co](https://docs.stacks.co) |
+| Stacks Explorer | [explorer.hiro.so](https://explorer.hiro.so) |
+| Developer Discord | [stacks.chat](https://stacks.chat) |
+| Stacks Forum | [forum.stacks.org](https://forum.stacks.org) |
+| Stacks Foundation | [stacks.org](https://stacks.org) |
+
+### Get Help
+
+- Join the **#documentation** channel on [Discord](https://stacks.chat) for questions about contributing
+- Tag `@docs-maintainers` on GitHub for urgent documentation issues

docs/build/README.md

@@ -84,7 +84,7 @@ There is also a subsection of example Clarity contracts where you'll find **star
 
 We all have different styles of learning. If you've already got a good concept of web3 fundamentals and want to get a quick taste of what the DevEx is like on Stacks, then check out the [Developer Quickstart](get-started/developer-quickstart.md). Or find the path that clicks for you — and if bandwidth allows, tackle them all!
 
-<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><strong>Try the Developer Quickstart</strong></h4></td><td>Your 0→1 guide for building a Clarity contract and app on Stacks.</td><td><a href="get-started/developer-quickstart.md">developer-quickstart.md</a></td></tr><tr><td><h4><strong>Start Learning Clarity</strong></h4></td><td>An easy starting point for learning smart contracts.</td><td><a href="get-started/clarity-crash-course.md">clarity-crash-course.md</a></td></tr><tr><td><h4><strong>Bitcoin Primer Tutorial</strong></h4></td><td>A comprehensive end-to-end experience to building full-stack dApps on Bitcoin.</td><td><a href="https://app.gitbook.com/s/skGYu79qDNfITOqDNU3s/bitcoin-primer">Bitcoin Primer</a></td></tr><tr><td><h4><strong>Earn a Stacks Developer Degree</strong></h4></td><td>A hands-on Stacks bootcamp by LearnWeb3.</td><td><a href="https://learnweb3.io/degrees/stacks-developer-degree/">https://learnweb3.io/degrees/stacks-developer-degree/</a></td></tr><tr><td><h4><strong>Watch Our Hands-On Videos</strong></h4></td><td>Developer insights and workshops from the Stacks ecosystem</td><td><a href="https://www.youtube.com/@stacks-developers">https://www.youtube.com/@stacks-developers</a></td></tr><tr><td><h4><strong>Clarity Development Using Clarinet</strong></h4></td><td>The smart contract toolkit for Stacks</td><td><a href="/broken/pages/UK5Kgh2MHLoQvfoFVnLr">Broken link</a></td></tr></tbody></table>
+<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><strong>Try the Developer Quickstart</strong></h4></td><td>Your 0→1 guide for building a Clarity contract and app on Stacks.</td><td><a href="get-started/developer-quickstart.md">developer-quickstart.md</a></td></tr><tr><td><h4><strong>Start Learning Clarity</strong></h4></td><td>An easy starting point for learning smart contracts.</td><td><a href="get-started/clarity-crash-course.md">clarity-crash-course.md</a></td></tr><tr><td><h4><strong>Bitcoin Primer Tutorial</strong></h4></td><td>A comprehensive end-to-end experience to building full-stack dApps on Bitcoin.</td><td><a href="https://app.gitbook.com/s/skGYu79qDNfITOqDNU3s/bitcoin-primer">Bitcoin Primer</a></td></tr><tr><td><h4><strong>Earn a Stacks Developer Degree</strong></h4></td><td>A hands-on Stacks bootcamp by LearnWeb3.</td><td><a href="https://learnweb3.io/degrees/stacks-developer-degree/">https://learnweb3.io/degrees/stacks-developer-degree/</a></td></tr><tr><td><h4><strong>Watch Our Hands-On Videos</strong></h4></td><td>Developer insights and workshops from the Stacks ecosystem</td><td><a href="https://www.youtube.com/@stacks-developers">https://www.youtube.com/@stacks-developers</a></td></tr><tr><td><h4><strong>Clarity Development Using Clarinet</strong></h4></td><td>The smart contract toolkit for Stacks</td><td><a href="clarinet/overview.md">Clarinet Overview</a></td></tr></tbody></table>
 
 
 

docs/build/clarinet/quickstart.md

@@ -137,5 +137,19 @@ $ (contract-call? .counter count-up)
 $ (contract-call? .counter get-count tx-sender)
 u2
 ```
+
+{% hint style="info" %}
+**Exiting the Console**: To exit the Clarinet console, type `exit` or press `Ctrl+C`. Your contract state will be reset when you restart the console.
+{% endhint %}
 {% endstep %}
 {% endstepper %}
+
+***
+
+## Common Beginner Mistakes
+
+{% hint style="info" %}
+For a deeper dive into common pitfalls and how to avoid them, check out this blog post: [5 Common Clarity Development Mistakes and How to Fix Them](https://dev.to/rajuice/5-common-clarity-development-mistakes-and-how-to-fix-them-3dl).
+{% endhint %}
+
+**A quick note on the `.` prefix**: In the Clarinet console, the `.` before a contract name (e.g., `.counter`) is shorthand for the fully qualified contract identifier. When you deploy contracts locally, they are deployed under your default deployer address. Writing `.counter` tells Clarity to look for the `counter` contract deployed by the current transaction sender. Without the `.` prefix, Clarity cannot resolve which contract you are referencing, and the call will fail with an `UnknownContract` error. This is one of the most common mistakes new Clarity developers encounter.

docs/build/stacks.js/networks.md

@@ -42,3 +42,4 @@ const address = privateKeyToAddress(privateKey, 'devnet');
 {% hint style="info" %}
 For more advanced workflows, pass a custom network configuration object. See the `@stacks/network` package for details.
 {% endhint %}
+

docs/build/stacks.js/overview.md

@@ -57,14 +57,37 @@ npm install @stacks/common
 
 Other available packages include:
 
-* `@stacks/auth`
-* `@stacks/encryption`
-* `@stacks/network`
-* `@stacks/stacking`
-* `@stacks/transactions`
-* `@stacks/bns`
-* `@stacks/common`
-* `@stacks/wallet-sdk`
+| Package | Description |
+| ------- | ----------- |
+| `@stacks/auth` | Authentication and identity management for Stacks applications |
+| `@stacks/encryption` | Encryption utilities for secure data handling |
+| `@stacks/network` | Network configuration for mainnet, testnet, and devnet |
+| `@stacks/stacking` | Stacking (PoX) operations and delegation management |
+| `@stacks/transactions` | Transaction building, signing, and broadcasting |
+| `@stacks/bns` | Bitcoin Name System (BNS) name registration and lookup |
+| `@stacks/common` | Shared utilities and types across Stacks.js packages |
+| `@stacks/wallet-sdk` | HD wallet generation and account derivation |
+
+***
+
+## Quick Example
+
+Here's a simple example of reading data from a smart contract:
+
+```typescript
+import { fetchCallReadOnlyFunction } from '@stacks/transactions';
+
+const result = await fetchCallReadOnlyFunction({
+  contractAddress: 'SP2C1WREHGM75C7TGFAEJPFKTFTEGZKF6F9D4RK2D',
+  contractName: 'my-contract',
+  functionName: 'get-counter',
+  functionArgs: [],
+  network: 'mainnet',
+  senderAddress: 'SP2C1WREHGM75C7TGFAEJPFKTFTEGZKF6F9D4RK2D',
+});
+
+console.log(result);
+```
 
 ***
 

docs/learn/README.md

@@ -6,9 +6,17 @@
 For the official Stacks whitepaper: [https://stacks-network.github.io/stacks/stacks.pdf](https://stacks-network.github.io/stacks/stacks.pdf)
 {% endhint %}
 
+{% hint style="success" %}
+**Prerequisites for this section:**
+- Basic understanding of blockchain concepts (blocks, transactions, consensus)
+- Familiarity with Bitcoin fundamentals (UTXO, mining, halvings)
+- No programming experience required for conceptual sections
+{% endhint %}
+
 ### Stacks: The TL;DR
 
-Stacks activates the Bitcoin economy. Bitcoin is the most adopted, most valuable, and most decentralized cryptocurrency. The Stacks L2 enables fast, cheap BTC and full-featured smart contracts on the L2 without modifying Bitcoin itself. Users and developers can use BTC in their apps and pay gas fees with BTC. All transactions on Stacks L2 are secured by Bitcoin L1 with 100% finality, enabling you to build apps and digital assets that are integrated with Bitcoin security.
+Stacks activates the Bitcoin economy. Bitcoin is the most adopted, most valuable, and most decentralized cryptocurrency. The Stacks L2 enables fast, cheap BTC and full-featured smart contracts on the L2 without modifying Bitcoin itself. Users and developers can use BTC in their apps and pay gas fees with BTC. All transactions on Stacks L2 are secured by Bitcoin L1 with 100% finality, enabling you to build apps and digital assets that are integrated
+ with Bitcoin security.
 
 The Stacks layer for smart contracts has the following innovations that make it unique:
 

docs/operate/README.md

@@ -18,3 +18,29 @@ While you can run a node using these specs, it's recommended to assign more than
 * **1 TB disk** for Stacks node
 * **1 TB disk** for Bitcoin node
 {% endhint %}
+
+***
+
+## Quick Troubleshooting Tips
+
+| Issue | Solution |
+| ----- | -------- |
+| Node not syncing | Check your internet connection and firewall settings. Ensure ports 20443 and 20444 are open. |
+| Out of disk space | Increase disk allocation or prune old chainstate data. |
+| Connection timeouts | Verify your `bootstrap_node` configuration in the `[node]` section of your Stacks node config file (e.g., `stacks-node-mainnet.toml`) is correct and reachable. See [Stacks Node Configuration](../reference/) for details. |
+| High memory usage | Consider running only the Stacks node without a local Bitcoin node. |
+
+## Community Support
+
+* **Discord**: Join the [Stacks Discord](https://stacks.chat/) and ask in the #node-operators channel
+* **Forum**: Post questions on the [Stacks Forum](https://forum.stacks.org/)
+* **GitHub Issues**: Report bugs at [stacks-network/stacks-core](https://github.com/stacks-network/stacks-core/issues)
+
+## Health Check Recommendations
+
+Monitor your node's health regularly by checking:
+
+1. **Sync status**: Compare your node's block height with the [Stacks Explorer](https://explorer.hiro.so/)
+2. **RPC endpoint**: Test with `curl http://localhost:20443/v2/info`
+3. **Peer connections**: Verify your node has active peer connections
+4. **Disk usage**: Ensure you have at least 100GB free space for growth

docs/reference/README.md

@@ -100,7 +100,7 @@ This section contains configuration options pertaining to the blockchain the sta
 | rpc\_port  |          | RPC port of `peer_host`                                                                                               |
 | peer\_port |          | P2P port of `peer_host`                                                                                               |
 
-**Mining**
+#### Mining
 
 | Name                             | Required | Description                                                                                        |
 | -------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |