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!
Senior Technical Writer at Filebase
Web3 provides a lot of different technologies and workflows that Web2 websites aren’t using.
Web2 vs. Web3
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:
Research again: Products are always changing and updating - long-term research and updates will be required, especially in Web3.
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:
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?
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.