Full First Draft of Documentation Text

[poliwop]

https://www.notion.so/Documentation-9698c76d723c4bbba54fcbd8a52750fd

[KrisParuch]

first draft is completed, please review @poliwop .

most relevant feedback would be whether we want to use the nomenclature from the BSCI report or from the notebooks. I'd have to align accordingly based on your decision.

[poliwop]

@KrisParuch I'm not sure where the BSCI report vs my notebooks differ in nomenclature, if it's not obvious from your draft, can you point it out or at least give an example?

[KrisParuch]

@poliwop when you compare the sections 'formal definitions of variables' and 'formal definitions of mechanisms' you'll see that the tables come from the report and the mechanisms come from your notebooks. Then e.g. the agents asset holding $r_a$ vs $r_i^\alpha$ or the fees $f_P$ vs $f_Q$ differ and should be unified.

My take would be to choose the taxonomy that is as close as possible to the implementation or at least the model syntax - but then on the other hand the report is already finished. It would be great to have everything unified across all publications and implementations, but if not it sould at least stay close to the on-chain implementation. what do you think?

[poliwop]

still reviewing, but I'll wanna track changes in source control so I think the next step will be to move the existing text into github so that we can do that, even before any of my comments are addressed

[poliwop]

I finished the review, left a lot of comments... as mentioned above, please move this to source control before making changes so that I can track the critical changes specifically instead of having to re-read the whole thing. Probably best to make a branch for the update in Hydradx-docs, but the first draft doesn't have to be the actual web page since we're still working on getting the text right? OTOH, you'll want something that supports latex so maybe the web page format will be easiest...

I couldn't help myself and wound up making comments on language/presentation that aren't as important, I'm hoping it'll be pretty easy for you to tell which are these... probably makes sense to just keep those comments around for when folks outside the research team review the documentation. After you've moved this to source control, let me know when the more important changes are ready for review.