# 《给 Hardhat 的信：我的 Web3 技术写作启程》

By [RainWeb3](https://paragraph.com/@rainweb3) · 2025-10-09

---

> 我想说的是：编写完善、无障碍、流畅的环境搭建指南，只是我的起点。
> 
> 我相信，任何技术与工具，最终都是为人、为项目、为业务服务的。如果能**不依赖图片、不依赖流程图**（这些占用文档资源的形式），仅通过**文字描述的清晰度**和**步骤的明确性**，就能把技术的复杂度、工具使用的复杂度、版本冲突与不兼容的探索成本，彻底降低——
> 
> 那么，这种被极致解构并组织得流畅清晰的指引，本身就该成为技术体验的一部分。
> 
> 它应当让人感受到：技术本可以如此简单、直接、可掌控，就像我们今天使用 AI 工具一样自然。
> 
> 而我几乎很少见到这样的文档。
> 
> 每当我写文档时，总是本能地**极致细化**，只为确保未来再次经历相同场景时，不会踩坑、不会卡壳，甚至希望它能成为“**傻瓜式指引**”，像吃饭喝水一样顺畅。
> 
> 也许我的想法有些天真，或过于理想，但我愿意在学习中去做，在实践中调整。不同环境总有难以预测的问题，正因如此，我才更想做这件事——即便它暂时没有经济价值。

### 📝 说明

> 这不是一篇技术教程，而是一次坦诚的分享：
> 
> 为什么我更愿意写文档，而不是只写代码？
> 
> 希望这段文字能带给你一点力量。
> 
> 这是我在 Hardhat 官方 GitHub 仓库中回复团队的一段话，原文为英文。我选择保留英文原文，因为它已是公开 Issue 的一部分，且我希望全球开发者都能无障碍阅读。

* * *

> I'd like to share with you the motivation behind my actions. I'm a developer transitioning from Web2 to Web3, and I want to explain why this shift means so much to me.
> 
> While Web2 has evolved over the years with diverse tech stacks and a vast ecosystem, it also carries numerous longstanding issues. In recent times, especially within China, the industry appears to be approaching a stagnation point. When I discovered Web3, I was immediately drawn to its core principles: decentralization, openness, and user sovereignty. These values resonated deeply with me.
> 
> One major pain point in Web2 is the lack of proper documentation. Outside of a few top-tier companies, most organizations don’t prioritize maintaining technical documentation. Even when documentation policies exist, the quality is often inconsistent—written reactively to meet internal requirements rather than to support knowledge sharing. Critical information frequently gets lost between development phases, making it difficult to trace decisions or onboard new team members efficiently.
> 
> Moreover, most Web2 technologies and codebases are closed-source or only partially open. While this is understandable from a business perspective, it creates significant barriers for developers trying to learn or debug systems. Despite the large developer community, finding accurate, up-to-date, and comprehensive resources can be extremely challenging—let alone accessing knowledge about systems that are entirely proprietary or outdated.
> 
> In contrast, Web3 greatly reduces these issues. The transparency of on-chain smart contracts, which anyone can audit, represents a fundamental improvement. When I began learning Web3, my initial goal was to become a smart contract developer. However, as I documented my learning process, I realized I have a stronger passion and aptitude for creating detailed, beginner-friendly technical guides and tutorials.
> 
> Currently, the Web3 space lacks in-depth, well-structured documentation. While there are many learning platforms and video tutorials, they often leave learners to navigate numerous pitfalls on their own, consuming significant time and effort. If developers could spend less time troubleshooting tooling issues and instead focus on core aspects—such as business logic, security audits, user experience, gas optimization, and data accuracy (on-chain and off-chain)—it would greatly accelerate the growth and maturity of the Web3 ecosystem.
> 
> This insight inspired me to start building a personal Web3 knowledge base and to actively provide feedback to tools and educators I use. My long-term goal is to contribute meaningfully to the Web3 space—ideally securing a role in technical documentation, developer relations, or developer experience. I’ve found that writing documentation gives me far more motivation and fulfillment than coding itself.
> 
> For example, I’ve been learning through Patrick Collins’ excellent platform at [https://updraft.cyfrin.io/](https://updraft.cyfrin.io/). His courses are clear, high-quality, and very accessible. However, some parts—particularly around tooling setup and environment configuration—have become slightly outdated. I tried reaching out to him via Twitter DM, but couldn’t send a message. I also sent a friend request on Discord, which hasn’t been accepted—likely due to his busy schedule. Eventually, I submitted feedback through his platform, though I’m unsure if he’s seen it.
> 
> After that, I decided to file issues directly on the Hardhat GitHub repository, hoping to help other learners who might encounter the same challenges.
> 
> Regarding your suggestion about creating a new issue: for now, I don’t think it’s necessary. If I have additional feedback, I’ll organize it into a well-structured document and submit it as a new issue or discussion.
> 
> The documentation I’m creating may also serve as a helpful supplement for users navigating your official tools. With clear guidance, learners should be able to get up and running within 30 to 60 minutes, minimizing the need to jump between multiple sources.
> 
> As for why I haven’t translated my documents into English yet: I want to ensure accuracy, and I’m not confident that my English proficiency would allow me to properly review or refine machine-translated content. Inaccurate translations could mislead readers, which would defeat the purpose. Even in Chinese, as long as the logic and steps are clearly laid out, English-speaking developers can follow along effectively using translation tools or by tracing the detailed instructions.

---

*Originally published on [RainWeb3](https://paragraph.com/@rainweb3/hardhat-web3)*