This talk was presented at API The Docs Virtual 2022 event series on 9 November. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
Visit the talk listing page for an overview of all presentations!
Jessie Mongeon
Senior Technical Writer at Filebase
Jessie's presentation
Jessie's slides
Q&A
- Where would be an entry point for docs practices or more the novelties and differences, to learn?
- What do web3 APIs look like and how do you document them? Are they different from HTTP requests? Are there any common standards like the OpenAPI for HTTP?
What is Web3?
- A new version of the Internet.
- Often referred to as the decentralized web, or the ‘read-write-own’ version of the Internet.
- Growing rapidly - new technologies, tools, projects, every day.
- Uses blockchain networks.
- Uses decentralized storage.
- Uses digital identities.
- Uses digital assets (NFTs).
- Uses cryptocurrencies.
Web3 provides a lot of different technologies and workflows that Web2 websites aren’t using.
Web2 vs. Web3
Web2
- Is centralized.
- Uses traditional technology stacks.
- Often referred to as the read-write Internet.
- Data is owned by the platform and used for advertising.
- E.g. Google, Facebook, Amazon, Twitter, etc. are considered as part of Web2.
Web3
- Is decentralized.
- Uses new blockchain-based technology stacks.
- Often referred to as the read-write-own Internet.
- Data is owned by the user, not the platform.
- E.g. Ethereum, Polygon, Filebase, Alchemy, IPFS, etc. are considered as part of Web3.
Why does Web3 need docs?
- New technologies - blockchains, smart contracts, etc. - need docs for users to begin understanding and using them.
- More documentation leads to faster adoption and widespread utilization.
- Most Web3 tools and products use an API or new programming languages like Solidity to interact with and develop with their platform.
What do writers need to know to be successful when documenting and writing about Web3?
Researching: Consistent, constant research is required to learn about continuously appearing new products and tools, so that you can document how end-users can use them.
Writing: When documenting new products, keep in mind:
- What do end-users want to gain from using this tool?
- What applications and workflows will they be using? Other APIs?
- How might the docs need to be updated in the future?
Research again: Products are always changing and updating - long-term research and updates will be required, especially in Web3.
Should Web3 documentation look different from Web2 documentation?
API docs: Resembling other existing Web2 documentation can help accelerate the adoption of Web2 products and tools since the documentation format is something they are familiar with.
Product docs: Product docs in Web3 should be clear, concise and explain exactly what the product and 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 and takeaways in the future.
Successful API documentation:
- Needs clear, straightforward wording for instructions.
- For API docs, showcasing exact parameters along with possible responses with examples of both.
What users are looking for?
Clear instructions: Users want documentation that leaves no questions unanswered and avoids using complex language.
Familiar format: As users begin to move from Web2 to Web3, they want things in the format they are familiar with for easier adoption.
Docs written with their use-case in mind: Users want documentation that was written with their use-case in mind to avoid any confusion or uncertain expectations. Will they use other APIs?
In conclusion
-
Web3 - Web3 is the new version of the Internet that utilizes decentralized technologies like blockchain networks. Hundreds of new products and 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.
-
Familiar format - Web3 docs should follow formats that Web2 uses 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.
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.
