Dev Doc Walkthrough: TW+plor

--- ###### tags: `docs` --- # Dev Doc Walkthrough: TW+plor Monday June 27, 2022 ### React Docs (beta.reactjs.org) - Sidebar not particularly useful. *Home* doesn't have enough to it. - *Home, Learn, and API* might be compiled. - Nice to have a way to provide feedback and submit changes for errors - Looking for functions: want to see this first = "how do I use this function" - Left bar (meta contents) are important, but Right bar (page contents) are less so since the content will likely be scrolled - Rather **verbose** docs style. Could be distilled into lists. The closer to the actual code parameters, the better. - List of code parameters - Explanations of the parameters - As little explanation as possible (not too much narrative) - Prefer more declarative - **Big plus: edit code in the docs to witness examples of how it works** - Download - Reset - Fork (to CodeSandbox.io) - Multiple examples indexed in a single module might get lost, not seen - FAQ / Troubleshooting Sections: should remain high-level for browsing and avoid getting too deep in the weeds ### RainbowKit - More declarative: demonstrative, less narrative, showing over telling - Sections are succinct, informative, simple. - One sentence description - Code block - Link: read more, examples - Especially important for docs that wrap other libraries (like DH SDK) ### Ethereum Foundation - Zen mode is useless - Light/dark would probably not be used - Nice to have **diagrams** for illustrating advanced *concepts*. Can be overdone, should be careful. - Not so useful for getting deep into particular features ### Solidity Docs (hosted by RTD) - Nice visual hierarchies - Dense information, but still easy enough to find - Search: - Most info is found by navigating to the appropriate section and then scrolling - Search is still necessary though for certain keyword discovery ### General - Some docs are referenced because the components are already being used. Other docs are browsed to see if its something that might be used, to feel it out. These might constitute 2 distinct ways of browsing. - Knowledge graph might be distracting ### Existing DH Docs - Hierarchy is counterintuitive - Code Legos is 2 clicks away - Not as *declarative* as devs desire - Oscillates between far too much information or not enough (missing) - Format is inconsistent - Diagrams should be accompanied by succinct text - Some sections are just examples: no description, just code. Not enough. - Desire small chunks that are digestible. Avoid complex images/explanations that cannot be immediately consummed. - **Tutorials and contributing guidelines should not be alongside the code.** They should be separated, not stacked.