search

ethereum / hevm

symbolic EVM evaluator
https://hevm.dev
GNU Affero General Public License v3.0
225 stars 46 forks source link

Finish the docs? #430

Closed PatrickAlphaC closed 1 month ago

PatrickAlphaC commented 9 months ago

Been trying to play with hevm again, but having a really hard time due to the current state of the docs.

here

Can we add a minimal foundry example in here? I feel like that will enable a lot of people to access this tool.

joaovaladares commented 9 months ago

Agreed, I'm really having a hard time to even install it and make it usable in the first place

msooseth commented 7 months ago

Good news is, I started working on this. I'll create PR when it's ready :)

PatrickAlphaC commented 7 months ago

MY HEART

msooseth commented 6 months ago

Sorry, got side-tracked, doing it more this week :)

msooseth commented 6 months ago

PR #476 aims to fix this. Please give me some feedback if you like, I'd be happy for any improvement of the writing, etc! You can make a PR on the PR or just give feeback in-line :) Thanks a lot in advance!

PatrickAlphaC commented 5 months ago

awesome!!! Sure, so here is my long list of improvement points:

Needed pages in the docs:

  1. Installation

This might be redundant to the readme, but the docs should be the end-all-be-all, everything should be available to the devs in the docs!

  1. Getting Started

The Getting Started page should be the quickest way to reach the "aha" moment for a developer, and often it includes the installation. It will need to include the next piece:

  1. Quickstart

This is where a developer does a "speedrun" of running the tool you way you want it to be run. Sort of like a super fast tutorial. Maybe you have a demo app that you run hevm on to show how cool it is or something. Looks like maybe this is your dstest tutorial?

Optional sections

  1. Introduction

This could optionally be your overview section. Maybe it would be cool to include what projects are using it now? That's a bit more marketing, but you can do a little marketing in the introduction/overview section.

Those are the biggest improvement points for me.

msooseth commented 5 months ago

Thanks @PatrickAlphaC ! That was actually a good list. I tried squeezing some of that in, and I renamed/restructured some things to better match what you wrote -- users will likely be looking for those things, so it makes sense to cater to that. I'll see if I can improve it further. I think it's best to do it in waves rather than all in one go, although I feel like I have changed a lot already :)

Thanks again for your help,

Mate

msooseth commented 1 month ago

Hi @PatrickAlphaC I actually really took to heart your feedback. I mapped your ideas to pages at https://hevm.dev/ except for "who is using it". Though hopefully with hevm better integrated with Echidna, it'll be possible to show some good examples. I'll talk with the Echidna people and see what we can do. Otherwise, the mapping:

Unfortunately, it's not very clear to me how much Quickstart is supposed to differ from Getting Started. I think you probably do see a difference between the two, but I am just not close enough to the users to be able to. Can you maybe elaborate how the two should differ? Or do you know we can cover them both with https://hevm.dev/getting-started.html ?

I'd be happy for any feedback! Thanks again :)

PatrickAlphaC commented 1 month ago

WOW!!! This is already so much better!!! With minimal examples, people can see exactly what the tool is aiming to do!!

msooseth commented 1 month ago

Awww thank you! And thanks again for your kind feedback. I think I'm closing this issue :)