Hello everyone. After too many people with too little experience with blockchain application development began writing all sorts of documentations too early with too little structure, we ended up with lots of useless and outdated material, of which none, by the way, takes into account much of what the core dev team has actually left us. Instead of poking around in selected areas, it is important to provide a wholistic view on developing things on aeternity, that puts the components we have in a bigger picture. As I was thankfully asked to take on this topic (for the newer ones: because I developed a little something here and there in this regard in the past years… ), I designed a structure I would like to fill partially with what we have already but rewritten in a form that non-computer science level devs would have fun reading it, and partially with content produced by myself.
Please see this preliminary structure and tell me if you find something missing. I am focusing heavily on topics relevant for the practice, without neglecting overviews about why things were decided to work this way and what advantages that posts in comparison to other protocols, like say, Ethereum. Because do not want to be perceived as just another clone.
(Important: This is not the reference to components like the SDK or sophia, which should and will be fabricated in a structured manner, thankfully we have considerably more material ready to be used here that just needs to be structured and explained better. )
Documentation and Training material
Note: Higher-tier subtopics will be included in Highlevel top-topics at first, then moved into the lower-tier top-topics.
I think you should focus on module 2 first and build other materials and modules step by step. do we really need module 1 for æternity? I’d rather include a comparison to projects like Bitcoin and Ethereum in module 2 instead of providing basics (of course this can be added later on but I think æternity learning material is way more important)
for the following modules it would be cool to cover the features with a quite simple real world example that includes all aspects (contracts, oracles, AENS & pointers, UI, wallet-connection, …)
I think state channels should be the lowest priority for TRÆNING because they are currently not usable on mobile phones and thus “the average joe” probably won’t have that much interest in it. probably that’s just wasted time to provide materials here as long as [Withdrawn] State Channel mobile client is not existing.
in general I highly appreciate this effort. I wanted to provide training material and a course for æternity as @ae-omar knows but realized that this is too much work for me to do in my spare time.
at the end I hope that this is not another initiative that will be skipped and end with outdated material at some point of time.
@marco.chain
I share your opinion, that’s why I’ve flagged Chapter 1 as Tier 2. It’s not critical to get going with AE for people who know about smart contract protocols like ours, but for non-crypto devs it is inevitable to understand the basics. The channels come at the end, but nonetheless, statechannels are what sets us way ahead of other protocols. They were very expensive to develop, and we shouldn’t let it fall under the table.
@Janson good point. Where would you propose to put that ?
Thank you for your feedback guys, it is really appreciated.
@nikitafuchs.chain amazing! Would you perhaps consider developing this guide as some sort of a ‘live wiki’ be the most productive/fast/responsive approach? I’m sure lots of folks know a lot - and it would reduce the effort/time needed on your part.
Yes, the plan is to have the originating material on github, so people can submit and review PRs. This original material will be kept in a form that specialcother tools can parse and add extended features to.
Very nice, this guide reminds me of when i made a guide about the realization of projects in the custom cryptocurrency platform MintMe. in the material he talked a bit about how people could carry out their projects through the creation of tokens, being able to offer their projects as a service to other people and monetize it. they can also support the other projects.
Quick update: I’m back from vacation and laying the groundwork for this, some sneak peek of how to easily find the info you need and contribute to the docs in an efficient and productive way. I’ll share the link as soon as it goes online, so people can rush in with their remarks on a finally readable documentation that will drive the adoption of AE.
This is to break out the documentation we have slumbering in the depths of github for ages and make it available as a technical reference, presented in a standard format people are used to, especially from the blockchain sphere: Solidity — Solidity 0.7.0 documentation It is not intended to compete with any efforts writing tutorials or best practices, but rather to give people a better accessible quick reference to go to when in need of information than walls of text inside convoluted collections of markdown files on github. Putting it in readthedocs makes things more clear, having a better overview now made me notice several lacks in the sophia doc yesterday that were not that obvious in the big long MD file on github. When writing tutorials & co, the community just shall have this as a more readable and better navigatable thing to point to than just a long text on github.
@marco.chain I’m just waiting for some GH permissions and it will be there. It is a slightly restructured form of the existing sophia doc, but being able to look at it in a more accessible way should definitely spark ideas among the community where and how to improve it, while still being able to propose and discuss PRs for that on github.
@Vikram nice idea, once we have the basic one halfway up and running, I will definitely consider pimping it up. the cool thing though about the standard layout is that people, who read these readthedocs like others do with harry potter, are familiar with the overall appearance, and it’s somewhat easier to consume information if you look at something that seems familiar to you.
Important info: I need to run to Apple and leave my computer for repairs, after I get it back I’ll move things to the official AE repo once we polish a things or two. You guys can open up PRs/ issues in my repo until then, I’ll participate through some backup means meanwhile and add @hanssv.chain as a collaborator, too.
Edit: As pointed out by hans, the info in the reference is “too new” and contains things that are not put in place yet, so don’t be disappointed please I will ‘downgrade’ it all for the time being.
We are making progress here, information becomes more accessible. As of yet, if you wanted to find information about coding in sophia, you were greeted with the old doc still shown at the top:
Being able to access information fast makes building stuff a lot easier. We can push the new docs on google way higher by using links to it as reference to different sophia related topics here in the forum!
Is there a way for us to announce these updates to the public in sections? I know you mentioned some of these are not public information yet–maybe those can be made private while the rest is public?
Would be nice to be able to announce to the public that the documentation hub is slowly being updated and for them to see it without the internal-only sections. Otherwise, it might take until next year before we can let the public see this at all (depending on how much needs updating).
No no, the publicly hosted new doc is now public and can be communicated publicly. One thing though: The new URL is https://aeternity-sophia.readthedocs.io/ , as the last one was chosen unintendedly and is too long.
Next major step taken: We finally have a well-browsable, well-readable JS SDK documentation / reference, which should also pop up on your google searches, too:
Now that things are more clear, it’s easy to see where the docs are still lacking input - a good point for the community to get engaged with me and the rest of the team on this, once the new doc is merged to master - pr is out: https://github.com/aeternity/aepp-sdk-js/pull/1077
Seems like we can really start going on the TRAENING in a few ?!
), I designed a structure I would like to fill partially with what we have already but rewritten in a form that non-computer science level devs would have fun reading it, and partially with content produced by myself.
I will ‘downgrade’ it all for the time being.
