Some feedback on the current documentation for devs

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?

7 Likes

I agree especially with the sentiment about animation.

Regardless of the content or the ability the reader has to parse it the vehicle information is communicated in does A LOT for the initial perception and bias they will approach the subject moving forward.

Reading a wall of text vs having a clean animation does a lot for getting that initial draw-- do you think someone new to Oasis would rather see a clean animation or a 5 page document? That being said I am not disparaging info dumps and there is 100% merit to that, but I truly feel that info graphs / animations are crucial for modern presentation of ideas.

This is an excerpt of an outdated animation i did of one of the oasis info graphs- it took me no time to do and programs like AE make this sort of animation incredibly quick. (heavily cut and compressed to gif for upload have it in mp4 format) Especially when doing stuff in crypto which I find to be overly leaning to isometric and cooperate art.

oasis

3 Likes

Yeah I agree. Especially with crypto and something like Sapphire where concepts are so novel. It has to be relatable to something that already exists in order for you to make sense of it (and then use it)

1 Like

Quality posts! Exactly the kind of stuff we need!

Bumperino

1 Like

Thank you, Slime, for offering your valuable feedback. I have forwarded your comments to the appropriate team for review.

2 Likes

This is a great post on both accessibility and ease of documentation for developers; which this entire should be about.

Hopefully this should be the focus for the foundation now to get documentation in order for hackathons and grants

1 Like

This is really great work, and a perfect example of how we could make our docs more visually engaging. Passing this along to our design/web team in case they missed it!

2 Likes

Another thing to mention that I just noticed:

The current docs have a developer section with a subsection “How to build” that only shows videos from the YouTube channel, but then it’s really the blue “Build on Oasis” link that has the more practical steps. Perhaps you could put that blue button in two places, once where it currently is at the top right, and again in the “how to build” section.

That way a dev doesn’t give up looking after only finding the videos.