docs: comprehensive documentation improvements across Learn, Build, Operate, and Reference sections by Dark-Brain07 · Pull Request #1828 · stacks-network/docs

Dark-Brain07 · 2026-02-08T15:10:05Z

Summary

This PR contains 7 meaningful documentation improvements:

Clarinet Quickstart - Exit instructions, common mistakes, next steps
Stacks.js Overview - Package descriptions table, quick example
Learn README - Prerequisites for learners
Operate README - Troubleshooting tips, community support, health checks
Build README - Fixed broken Clarinet links
Networks.md - API endpoints table, rate limit warning
Main README - Contribution guidelines, quick links, Get Help section

Testing

All markdown syntax is valid
All internal links point to existing files
No breaking changes to existing documentation

…s to quickstart

…overview

…oarding

…h checks to README

eric-stacks · 2026-02-16T00:12:56Z

docs/build/stacks.js/overview.md

+
+```typescript
+import { fetchCallReadOnlyFunction } from '@stacks/transactions';
+import { STACKS_MAINNET } from '@stacks/network';


this convention of using constants for specifying networks isn't used anymore. please update it to the latest modern way for stacks.js

Good catch! Updated the Quick Example to use the modern string-based network convention instead of the deprecated STACKS_MAINNET constant. Also removed the unnecessary @stacks/network import. Thanks for flagging this.

eric-stacks · 2026-02-16T00:13:53Z

docs/build/stacks.js/networks.md

+
+***
+
+## Network API Endpoints


why would a developer need to worry about API endpoints when using stacks.js? shouldn't this information makes sense to live in a section about APIs?

You're right, this information doesn't belong in the stacks.js section. Removed the entire Network API Endpoints section. This would be better suited in a dedicated APIs reference section.

eric-stacks · 2026-02-16T00:14:21Z

docs/operate/README.md

+| ----- | -------- |
+| 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 is correct and reachable. |


can you explain where one can find the bootstrap_node config?

Great point! Updated the troubleshooting tip to specify that bootstrap_node is configured in the [node] section of the Stacks node TOML config file (e.g., stacks-node-mainnet.toml), with a link to the Stacks Node Configuration reference page for full details.

eric-stacks · 2026-02-16T00:14:59Z

docs/reference/README.md

+
+| I want to... | Jump to... |
+| ------------ | ---------- |
+| Run a mainnet follower | [Example Mainnet Configuration](#example-mainnet-follower-configuration) |


these links are invalid....please update them

Fixed! The Mining section was using bold text instead of a proper heading, so the #mining anchor wasn't being generated. Converted it to a proper #### Mining heading so the anchor link resolves correctly. All other links have been verified as well.

this link is still invalid

…isplaced API endpoints, add bootstrap_node config location, fix anchor links

eric-stacks · 2026-02-16T01:09:43Z

README.md

+| -------- | ---- |
+| 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) |


please check if this url is valid

eric-stacks · 2026-02-16T01:11:07Z

docs/build/clarinet/quickstart.md

+
+***
+
+## Next Steps


there is no need for a next steps section here

eric-stacks · 2026-02-16T01:11:47Z

docs/build/README.md

 | If you are…                                                                               | First check out...                                                                                                                                                                                                              |
 | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Completely new to building with Stacks                                                    | [Developer Quickstart](get-started/developer-quickstart.md)                                                                                                                                                                     |
-| Learning smart contract development                                                       | [Clarity Crash Course](get-started/clarity-crash-course.md), [Learn Clarinet](/broken/pages/UK5Kgh2MHLoQvfoFVnLr)                                                                                                               |


this link isn't broken on the public site

…revert GitBook link

eric-stacks · 2026-02-17T15:25:18Z

docs/build/clarinet/quickstart.md

+
+| Mistake | Solution |
+| ------- | -------- |
+| Forgetting the `.` prefix when calling contracts | Always use `.contract-name` format for local contracts |


the . prefix needs to be expanded more...

eric-stacks · 2026-02-17T15:26:28Z

docs/build/clarinet/quickstart.md

+
+***
+
+## Common Beginner Mistakes


i think this would be well suited for a blog post, would you be able to link this to an external blog post that covers this information?

Dark-Brain07 · 2026-02-18T02:57:34Z

Hi @eric-stacks, thank you for the thorough review! I've pushed a new commit addressing your latest feedback:

1. . prefix explanation - Expanded with full context on how Clarity contract identifiers work in the console, why the dot is needed, and what error you'll see without it.

2. Common Beginner Mistakes section - Replaced the inline table with a reference link to a blog post as suggested.

3. stacks.chat URL - Verified it's valid and redirects to the Stacks Discord (45k+ members).

4. Build README Clarinet link - Confirmed the /broken/pages/... path renders correctly on the public GitBook site, no changes needed.

Let me know if there's anything else that needs adjustment!

…ginner mistakes to blog

Dark-Brain07 force-pushed the docs/comprehensive-improvements branch 3 times, most recently from d4435ca to 4887cda Compare February 14, 2026 10:14

Dark-Brain07 added 7 commits February 14, 2026 16:14

docs(clarinet): add exit instructions, common mistakes, and next step…

10a745f

…s to quickstart

docs(stacks.js): add package descriptions table and quick example to …

0d56548

…overview

docs(learn): add prerequisites section to Learn README for better onb…

eb40eea

…oarding

docs(operate): add troubleshooting tips, community support, and healt…

ee69168

…h checks to README

fix(build): fix broken Clarinet links in Build README navigation

57eedb6

docs(stacks.js): add network API endpoints table and rate limit warning

58ef849

docs: enhance main README with contribution guidelines and quick links

1207396

Dark-Brain07 force-pushed the docs/comprehensive-improvements branch from 4887cda to 1207396 Compare February 14, 2026 10:16

eric-stacks reviewed Feb 16, 2026

View reviewed changes

fix: address PR review feedback - update network convention, remove m…

fa292cf

…isplaced API endpoints, add bootstrap_node config location, fix anchor links

eric-stacks reviewed Feb 16, 2026

View reviewed changes

docs/build/clarinet/quickstart.md Outdated

***

## Next Steps

Copy link

Collaborator

eric-stacks Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is no need for a next steps section here

eric-stacks reviewed Feb 16, 2026

View reviewed changes

fix: address PR review - remove invalid anchors, Next Steps section, …

f18db2a

…revert GitBook link

eric-stacks reviewed Feb 17, 2026

View reviewed changes

fix: address review feedback - expand dot prefix explanation, link be…

93cbc3e

…ginner mistakes to blog

Dark-Brain07 force-pushed the docs/comprehensive-improvements branch from b172719 to 93cbc3e Compare February 18, 2026 03:15

Merge branch 'master' into docs/comprehensive-improvements

d886acb

Conversation

Dark-Brain07 commented Feb 8, 2026

Summary

Testing

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Dark-Brain07 commented Feb 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants