How I work
I find it best to use these steps:
-
Identify the core functionality.
- In the case of MUD, this is adding a table and using it in a
System↗. - In the case of Optimism, this is deploying a contract ↗.
- For tevm, this is forking a blockchain and communicating with a contract inside the forked blockchain ↗.
- In the case of MUD, this is adding a table and using it in a
-
Write a tutorial that uses the core functionality. Even though the point of the tutorial is to implement the functionality, it needs to be a complete application with observable results. There are two reasons for this:
- Prove to myself that what I’m writing is accurate, that there are no missing pieces, etc.
- Provide readers with the psychological payoff of seeing that whatever they did works.
During this process I typically come across some ideas to improve usability.
-
Based on the tutorial, figure out what reference information is needed. This depends on the way to access the functionality: TypeScript calls, Solidity calls, transactions, etc.
-
Write tutorials about the more advanced features of the product. The decision which advanced features are most important to have tutorials for can come from product mangement, customer support questions, etc.
These tutorials also need to be complete, show how the feature solves a problem with observable results.
How I work with your developers
I try to figure things on my own if possible, but I will need a victim Subject Matter Expert for questions, especially to get things running at first.
Once I have draft documentation, I need somebody knowlegeable to review it.
Code samples typically work (it’s easy to see when they don’t), but the explanation why they work may be inaccurate, or there might be edge cases I did not consider.