[DOCUMENTATION HUB] Updates, Requests, Questions and Feedback


#1

Hey æ people,
we’re working on renewing our documentation hub right now and I’m curious if anyone has any improvement proposals or even missing documentation about a specific part in general?

Looking forward to hear feedback from you! :partying_face:

Happy coding & (almost) weekend everyone! :muscle:

Link to GitHub repository (work in progress!): https://github.com/aeternity/documentation-hub


#2

Hey Pegah,

We are developing a Java/Kotlin SDK for Aeternity Epoch and find the Swagger documentation to be lacking.

What we would like to see is documentation with real examples of request and response data.
For example - in the /transactions api endpoint on aeternity.com/api-docs it only mentions it like this

{
  "tx": "tx"
}

where we don’t know how the tx parameter should be formatted. For the response, we also don’t have any specific data - only this:

{
  "tx_hash": {}
}

where we don’t know how the tx_hash is enconded nor how this object looks.

What we would like to see is something similar to what we’ve done with our documentation:

https://docs.ampnet.io/

Each endpoint has a request and response section with actual data used and actual responses received


#3

I’ve posted a few issues here https://github.com/aeternity/documentation-hub/issues i’ll add additional requests that reach me here in the forum and if they are legit i’ll create a new issue on GitHub.


#4

Hey guys. I will leave my feedback below.

It’s just my opinion, I may be wrong, the problem may be in me, but some of these things can be helpful.

  1. The Sophia documentation is a little bit chaotic and in most cases it’s not straightforward.

  2. Two source of documentation and both are quite different https://dev.aepps.com/aepp-sdk-docs/Sophia.html and github/aeternity/protocol/blob/master/contracts/sophia.md

  3. You should have a standalone section “Sophia by Example”, but I guess that is why you have “Tutorials” repo in GitHub.

  4. I had to look into this repo in order to understand some fundamental things github/aeternity/aesophia/tree/master/test/contracts

  5. A lot of things in the docs that are still missing in Sophia (yes, some of them are marked as * not yet implemented * but there are also such which are not marked)

  6. This one is very influenced from my previous experience with Solidity and the lack of experience with functional languages, so maybe I’m wrong.
    In order for Aeternity to succeed, it needs to attract a lot of developers that are building applications on top of Aeternity (yes, I know that’s why you have Ventures and Ventures are doing great, but still) and in order that to happen the development should be done easily. I cannot see ease development with Sophia. The immutability part is great, but if you have nested objects it’s pain in the ass to make updates on the state. Maybe some “helper” functions? I teach “Smart contract development with Solidity” in the local software university and I can assure you that the curve of learning Solidity will be much better than Sophia for newcommers.

  7. It is not clear how to decode error messages (and not only error messages) and I have to ask multiple times for decoding errors like cb_YXJpdGhtZXRpY19lcnJvci3L8ZY=

  8. Still missing: github/aeternity/aepp-middleware/issues/4 which is needed to show some historical data to our users.

  9. It is not clear how to subscribe for events emitted from the smart contracts which is a huge part that is needed to provide better UX.

  10. Dev tools are a must - thanks to Milen Radkov we now have VSCode extension for Sophia. There is a need for static/dynamic analysis tools and stand-alone compiler.

  11. When I started updating our smart contract using the latest features - namespaces, libraries and safe math I realized (too late) that the compilers provided by https://testnet.contracts.aepps.com/ and forgae wasn’t updated to support those features, so I had to roll-back. So if it’s possible to have a single source where we can get the latest updates on the tool-chains (forgae, testnet, hardforks) and their status. That would be perfect.

  12. It happens too often that something that I need can be done using some “erlang magic”, but cannot be done using the JS SDK.

  13. I don’t know if you do that with everyone, but everyone is showing some great technical support! I literally received answers in a matter of minutes by John Newby, Dimitar Velev, Philip Piwowarsky, Naz, Nikita, Valentin, Hans, Andrea (sorry if I missed someone). Wonderful job.

This is it. I hope this was helpful.

P.S. I can post only 2 links here, which seems strange.


#5

Sophia and Functional Programming is something that attracted me the most in Aeternity. Development experience is 100x better than in Solidity.


Aepp-sdk-java (v1.1.0) was released today
#6

How does a perfect language documentation looks for you? What would you say we should improve?

More examples and comparison maybe? Any other things?

Thanks you!


#7

Check this out: https://solidity.readthedocs.io/en/v0.5.5/solidity-in-depth.html

The way it is structured works best for me. Also check this: https://solidity.readthedocs.io/en/v0.5.5/solidity-by-example.html


pinned #8

#9

Can i suggest to share a link to the current state of the documentation hub here? I guess its this one, correct?

@kraykov i think the best Sophia docs can be found here https://github.com/aeternity/protocol/blob/master/contracts/sophia.md it is a bit hidden underneath

Smart Contracts > Sophia: The first contract language

I agree that we need to make this more visible. But remember, the documentation is WORK IN PROGRESS


#10

I can share my current thoughts and experience:

  1. Sophia Documentation inside the Github Markdown is a bit inconvenient to work with. Perhaps, it would be better to have standalone site like Solidity has, where on the left hand side one can see all the available sections and topics, so that observability and navigation would be much better.

  2. So far I have to read source code of Javascript SDK, Aeternity, Forgae and test code for contracts to find particular thing for my own project.

  3. Perhaps, you should open second support channel on stackexchnage/stackoverflow in parallel with this forum. Internet Search of stackoverflow is working great, so that it will be easier to search for some answer or question. Then, you could decide whether to maintain community support in both places or only for one.

  4. Sophia remote contract example. I have been struggling to find an example on how to do that.

  5. In general, Sophia is quite small and efficient language. Current documentation is there, but it is smashed around different places and repositories. I would suggest to structure it and centralise in one place.

  6. One more time, Sophia design is great. However, do you consider to add support of postfix notation for data types? For example, for option I do like this:

private function enoughGrade(f: option(int)): bool =
    getOrElse(map(f, (g) => g =< state.minGrade), false)

I would like to do smth like this:

 f.map((g) => g =< state.minGrade).getOrElse(false)

#11

First of all thank you very much for your helpful and detailed feedback.
I’ve one question: Could you be more precise regarding to point 1 and share link of the GitHub repository (Sophia Documentation) you’ve been pointed to please?

Thank you in advance! :slight_smile:


#12

Welcome. I use both pages:


https://dev.aepps.com/aepp-sdk-docs/Sophia.html


#13

Yes. This is not a long term solution. Its only the first step to collect all resources and make them easily available for everyone. We discussed to use something like gitbook.com in the future.


#14

@pegah the referral when you click on “Smart Contract” here is wrong. It sends you to protocol/node/api/contract_api_usage.md

But it should point here https://github.com/aeternity/protocol/blob/master/contracts/contracts.md

Also the sub-categories from that file are missing.

Is it better to make an PR or is it better to post such things here


#15

I’ve increased my efforts towards cultivating the ELI5 (explain it like i’m 5) philosophy among the core dev team over the last week. After being a little stumbled first, I think they understood. It’s also flowing into the engineering/design considerations more and more (e.g. type of input APIs require - highly overeingineered stuff vs. no-bullshit bare-minimum information with everything else built around by the software itself) Look at the impact on the compiler documentation (by Hans and Robert): https://github.com/aeternity/aesophia_http this is among our most naturally-speaking documented component of all right now, one can use the compiler without any technical knowledge even, just by copy-pasting and then learning by hacking around with the given example. it doesn’t get easier than this. This is my goal for the rest of our components.


#16

Thanks for pointing out! PR or at least issues would be great! :slight_smile:


#17

I just created a PR for aeternity/protocol/blob/master/contracts/sophia.md to solve one of your problems with adding a table of contents for a better overview at least: https://github.com/aeternity/protocol/pull/325