Hello everybody! 
First things first: The latest hæckathon we made was not just for the fun, of course. Around 40 participants filled out our survey on how well they liked which part of our ecosystem and how well they went along with them so far.
Second, the team elaborated some measurements to improve the developer experience based on these findings and our own thoughts.
Third, I drafted a plan on how to possibly tackle all this. As I haven’t found the stone of wisdom yet, suggestions are welcome, as things might be missing or improvable.
Spoiler warning: Reading this post you may stumble over not-yet-announced awesome things - depending on how loud you scream “yes please why the hell is this not a thing yet ?!11!1” they eventually might be finished and released. 
But first, the survey findings: The rating scale questions were all regarding the experience with Sophia, the JS SDK, AEstudio, etc. The results can be seen here. The numbers are very encouraging, but we can and want to do better still.
Other questions were open ended.
Yes, I’ve read the total of around 200 responses, and so you don’t have to, here is a summary. It consists of summarized requests, iconic responses and noteworthy quotes.
What would it need for you to continue BUIDLing with æternity after the hackathon?
- Tutorials, examples, guides, use cases, more extensive documentation
- “More tutorials that better match to aeternity studio.”
- More content on Youtube, including tutorials and presentations.
- Developer tools for faster testing
- “Virtual meeting to get me up to date about aeternity its requests and further wishes.”
- Support - Have a chat / contact person to ask questions related to the development.
- Easy to use frameworks, and tutorials on using them
- Information about regulatory aspects
- " stimulating demand of AE"
"I would like to have more sophisticated tutorials with near to production ready apps, so people could have better idea of how a particular use case might be implemented. Beside this, I found Aeternity community very supportive "
What could be improved about the onboarding with the JS SDK?
- Showing how to use the SDK effectively to connect to user’s wallet
- Step by step tutorials
- best practices and examples
- More tools for development and testing
- “More code examples starting from beginner to complex”
“Explanations on all the different parameters for SDK initialization and usage examples would really help. And for example it wasn’t very clear for me how to go from zero to getting up and running with the Superhero wallet through the SDK, and therefore I stuck with using the Base æpp in the end.”
What could be improved about the onboarding with Sophia?
- Documentation, especially examples (also for various use cases), guides and tutorials
- trainings / bootcamps
- more convenience features in AE studio
- videos and high level documentation
- “More step by step videos building stuff”
- “I think if there will be a book about will help alot.”
- “Maybe it can be More simpler to understand”
“there should be more examples. Sometime the syntax used to explain a Primitive is not familiar for those who are not used to coding. AEStudio platform is very useful,”
“Documentation that breaks down concepts into much easier snippets. I would also suggest to have concepts mapped to most frequently used software engineering languages. For example: how can looping be done in Sophia. How do conditional statements work in Sophia etc. And then move to the more complex Blockchain stuff like chain, transactions, signatures etc.”
“it’s a ML derived language, not strictly straightforward for someone coming straight out of OOP language”
“Rebrand Sophia to something easier to find”
Misc
“I had a frustration with installing Aeternity while following a github instruction; suggesting a change in max le and process sizes. It was quite difficult to get the machine back to life, in a recovery mode.”
WE HEAR YOU.
That’s why @radrow.chain, @philipp.chain, @bruteforce.chain, @gorbak25 and I put together the following list of ideas and suggestions (most of which aren’t new) to improve the developer experience to make building on æternity more attractive. Going by name, leaving out recurring points:
- sophia step debugger [like Ethereum has]
- better aex2 samples
- maintained documentation in general
- maintained SDKs in different languages (currently the most advanced one is just JS)
- finalize the erlscripten → purescript → javascript HTTP compiler so it can run client-side
- performance improvement on AEproject (as mentioned in Nikita’s doc)
- spend more time on sophia tools - syntax highlighters, lang server, linter, specification on proper way to document contracts, hints and suggestions (check sol-hint)
- wallet support of state channels (or different stripped down example of wallet that supports state channels)
- better error messages all around
- middleware explorer to be updated (currently wip)
- repl is a very good tool - make it more integrated in different places (aestudio etc.)… (not sure how well it is maintained though).
- sophia factory pattern !! - very much needed. [deploying contracts from contracts, specs proposal here
@gorbak25 and @radrow.chain came around with a component which plays an essential role in the development in other blockchain protocols: A “sandbox node client” for development and testing. The absolute swiss-army-knife-standard used by every dev in ethereum is Ganache. Pushing for this since 2019 brought little success unfortunately and we ended up with AEproject turning from a temporary solution to an everlasting one. But it doesn’t do it. So Radek and Grzegorsz not only built one because they need it for developing and testing the hyperchains staking contract. It even has potentially half a dozen BRUTALLY awesome features that don’t exist in the Ethereum ecosphere. 
It’s part of the node already but not exposed for API usage yet though. But more on that in a separate thread soon, and you can take a sneak peek at features at the end of… Last but not least… the / a
Plan:
SDK docs:
Looks, quantity and quality:
Quantity:
Many commands/operations do not provide an example. Those could be taken to some degree from the SDK tests.
Quality:
-
The explanation and the example of the commands must not be as concise/terse as possible but need to be understandable to a rookie, too. This also means cross-referencing other topics that are important in that context, so new developers understand how things relate to each other in the AE blockchain ecosystem.
Fictional Example:
Bad:
Creates an account stampGood:
Creates an instance of an account, which can be referenced where accounts are needed for signing a transaction (e.g. transferring AE or deploying/calling a contract) -
Not only all function
inputs need to be explained, but also all parts of thereturn.Good example for
code exampleandreturndata explanation from ethereum sdk, notice variations and commentary:
Looks:
Current the docs are being generated using JSdoc and formatted with handlebars. This makes sense for the aspect that developers write documentation right in the SDK code which is easier to maintain than some separate doc that will be always outdated somewhere. But both these libraries are very complex/use an own syntax and the default output gives a bad look and feel, as JSdoc is catering more to “oldschool”, techy and senior users that are not deterred by docs looking like this:
I am writing a parser that reformats critical output to a cleaner look like people would expect in 2021.
AE Studio
-
Beautify the transaction output like in Remix IDE for easier debugging and better access to information:
-
hyperlink transaction IDs and accounts to transaction explorer(s) / mdw
-
display decoded error message as return value in UI for easier error debugging (see screenshot, this is actually a really useful feature the FATE VM provides us)
-
add buttons/icons for quick copying of addresses and accounts to clipboard to UI where data is not available in plain text to improve workflow
-
add support for Sophia compiler JS library when ready for alpha testing - no more delays for errors and hints when typing code, less waiting when calling contracts.
-
create github repository where the editor can fetch example contracts from instead of hardcoding them and have UI section in the sidebar where examples can be accessed for various cases
Communication
All components we build need an active feedback loop, hackathons are very suitable for this, but devs need to go and communicate with users (devs building on AE) where they are (e.g. discord).
Example: Superhero Wallet integration JS module. It’s not enough that we can use it, we need to actively talk to people about it and see how we can make it implementable more easily (there is room for improvements currently) - in Ethereum it’s 1 line of code, Ethereum heavily benefited from that.
Developer Tools
For efficient development flow and testing, a sandbox chain is needed. It is an essential tool for all developers in Ethereum - luckily for us, it looks like we have a chain simulator now which has everything developers need.
Not surprisingly, Grzegorsz needed such a thing when developing the staking contract for Hyperchains and implemented it as a feature of the core node. From a marketing perspective, the advantage to a standalone client is the circumstance that this drives installs of the AE node and increases the chance of people running AE nodes.
Without going too deep into the feature set necessary for such a client, one can take Ganache (GUI) and Ganache CLI from Ethereum as example.
According to Grzegorsz, this so called dev mode of the node is already in a very advanced progress state, but not yet exposed via HTTP.
A TODO here is a GUI (simple electron app, also servable as standalone web app) The GUI can be forked off a middleware that simply points to the dev mode HTTP endpoints. A local GUI is important for accessing and setting all information quickly when developing on a local machine or when having a testing environment on a remote machine which runs just the dev mode in CLI and you need to access data and perform settings.
AEproject is just not suitable for a fluent development workflow and slows it down drastically.
Already existing features - dapp-devs know: most of that is totally nuts !
%%% - Optionally use state from a real block
%%% - Disable sync, gossip, peer discovery etc...
%%% - Start an in-ram chain simulator or even multiple ones if requested
%%% - instantly mine transactions pushed to it
%%% - Ignore PoW in the block headers
%%% - Use plugins almost anywhere
%%% - Provide an API for instrumenting the chain:
%%% * Start from real_block_hash - starts a chain simulator based on real-world state
%%% (might be taken from mainnet/testnet).
%%% * Start empty - starts a new chain simulator
%%% * Enable/Disable instant tx processing
%%% * Commit pending txs to a microblock
%%% * Clone on microblock/fork etc...
%%% * Set account state etc...
%%% * N new keyblocks on top of the current top block(or block with given hash)
%%% * Set the given block hash as the new top
%%% * Generate FATE execution traces, change contract code and state at will
TRÆNING
Once the documentation and dev mode is in a good shape, we should go forward with a guide on AE as I have put together already here
Chronology
Everything except the TRÆNING can be worked on concurrently and would directly benefit the developer experience.
