This document provides guidance for writing documentation about Web3 technologies. It begins with an introduction to the author and their background in technical writing. The document then discusses what Web3 is and how it differs from Web2. It emphasizes that Web3 documentation should use familiar formats from Web2, include detailed examples and code snippets, and use clear language to explain challenging new concepts. Constant research is important given the rapidly evolving nature of Web3 projects. The goal of documentation is to accelerate understanding and adoption of new decentralized technologies.
2. Hello!
My name is Jessie Mongeon
Senior Technical Writer at
Filebase
Self Published Author of ‘The
Ultimate Web3 Pocket Guide’
2
3. About Me
⦁ Senior Technical Writer @ Filebase -
Decentralized Storage and IPFS Pinning
Provider.
⦁ Self Published Author of ‘The Ultimate Web3
Pocket Guide’
⦁ First published in 2009 in a collection of poetry
⦁ Master’s of Science in Information Technology
Management
3
4. ⦁ Decentralized Cloud Storage + Geo-Redundant
IPFS Pinning Provider
⦁ S3-Compatible API
⦁ IPFS Pinning Service API - fully compliant
⦁ Documentation ranges from API docs, Web3
tutorials, and configuration guides to eBooks,
Whitepapers, and One-Pagers
4
5. In The Past Year:
⦁ 200+ Pieces of Documentation
⦁ Self published 540 page book ‘The Ultimate
Web3 Pocket Guide’ - a detailed technical
handbook for Web3
5
6. What is Web3?
- The ‘read-write-own’ version of the Internet
- Growing rapidly - new technologies, tools,
projects, every day
- Blockchain networks
- Decentralized storage
- Digital identities
- Digital assets (NFTs)
- Cryptocurrencies
6
7. Web2
- Centralized
- Uses traditional
technology stacks
- ‘Read-write’ Internet
- Data is owned by the
platform and used for
advertising
- Google, Facebook,
Amazon, Twitter, etc.
Web2 vs. Web3
Web3
- Decentralized
- Uses new blockchain-based
technology stacks
- ‘Read-write-own’ Internet
- Data is owned by the user,
not the platform
- Ethereum, Polygon,
Filebase, Alchemy, IPFS, etc.
7
8. Why Does Web3 Need
Docs?
- New technologies - blockchains, smart
contracts, etc - need docs for users to begin
understanding + using them
- More documentation leads to faster adoption
and widespread utilization
- Most Web3 tools/products use an API or new
programming languages like Solidity to
interact with + develop with their platform
8
9. What Do Writers
Need To Know…
to be successful when documenting and
writing about Web3?
10. Researching
New products/tools daily
means consistent, constant
research is required to learn
about them and how to use
them, so that you can
document how end-users can
use them.
Research, Write, then Research
Again
Writing
When documenting new products,
keep in mind:
- What do end-users want to gain
from using this tool?
- What applications/workflows will
they be using? Other APIs?
- How might the docs need to be
updated in the future?
10
Research Again
Products are always changing and updating - long-term research
and updates will be required, especially in Web3
12. Web3 Documentation Formats
API Docs
Resembling other
existing Web2
documentation can help
accelerate the adoption
of Web3 products/tools
since the documentation
format is something
they’re familiar with.
Product Docs
Product docs in Web3
should be clear, concise,
and explain exactly what
the product/tool does
and how users can
benefit from using it.
Many Web3 products are
still very early in
development and their
product mission might
be unclear.
Tutorial Docs
Highly visual tutorials,
with well documented
code examples are vital
to Web3 for users to
understand the tutorial
and how to replicate any
learnings/takeaways in
the future.
12
13. Successful API Documentation
- Clear, straightforward wording for instructions
- For API docs, showcasing exact parameters
along with possible responses with examples of
both
13
15. In Conclusion
Web3
Web3 is a new version of the
Internet that utilizes
decentralized technologies like
blockchain networks. Hundreds
of new products/tools emerge
weekly.
API Docs
Many Web3 products provide
an API that developers and
users need to utilize to interact
with their platform.
Research, Write, Research Again
Web3 is consistently growing and
changing since it’s very early in
adoption and development.
Consistent research is necessary to
stay updated.
15
Familiar Format
Web3 docs should follow
formats that Web2 docs use to
provide users with a familiar
format.
Detailed Examples
New Web3 technologies can be
hard to understand and utilize.
Detailed examples and tutorials
can help accelerate that
understanding.
Clear Language
Web3 contains enough new,
confusing terms. Docs should
stick to clear, simple language
for ease of understanding.