Hi all,
I wanted to voice some feedback over the current documentation. I should preface this that I am not a blockchain dev, although I have taken Dawn’s MOOC and built some small trading bots. However I am a veteran fullstack software dev with over a decade of experience, so I’ve seen every different kind of public documentation for all the libraries and tools I’ve used over the years, so I know what works and doesn’t work.
I understand that Oasis is still quite new and devs are more focused on getting something working before focusing too much on the documentation, however at this point, with Sapphire now released, I think the current docs could use a makeover.
I’ve tried to follow them more than once and each time it has immediately gone over my head, partly yes because I’m not a blockchain dev, but also because there seems to be many assumptions about the reader’s skill level by the author. It seems as if the author is writing to themselves rather than to a general blockchain dev who wants to use Oasis.
As a concrete example of some of this difficulty - when I go to the oasis website and click “Developers” and then “how to build”, it brings me to 3 videos. The first video is actually pretty good, but even that is not what most devs are looking for. I have to scroll midway through the video to see some actual code, but even that has a lot of “and you can see this is already done”, skipping over a lot. Granted it’s starter truffle code so many blockchain devs would be familiar.
When devs are wanting to use a tool, in my experience they are looking for standard docs like what you can find with Bootstrap css. I.e. Step 1. get the library with npm. Step 2. heres a hello world. step 3 heres all the library features and MANY examples via written code to use them. Developers don’t like scrolling through videos. We want code we can play with and examples of proper usage.
Another thing I think would help is primarly for visual learners. I noticed a lot of the same messages being sent by marketing like “add privacy to your dapp”. At least for me, that message doesn’t connect. I think more concrete examples, especially with visual abstractions, would be a big help.
Some ideas:
- Could you make visuals that show an existing dapp on Ethereum using Oasis for privacy? Perhaps even with animations?
- Make a more basic “Hello Sapphire” beginner guide that assumes the reader is just getting into blockchain.
- Make the homepage links for devs go directly to code, not videos.
What do you think?
