Poor documentation deterred developers

I’m a Cardano developer for 2 years. There’s little progress in documentation in this period.

For stake pool / cardano-node, the documentation from Cardano Developer Portal is really out of date. The video is 2 years ago and lots of stuff is incorrect and incoherent. Even no instructions for the hard fork.

For Native Script, the useful library cardano-serialization-lib to interact with dApps and light-weight wallet by @emurgo_io. The documentation was almost the same as a year ago. As a famous library from the official team, it’s not friendly for developers who want to step into Cardano.

For Plutus Script, has a horrible development experience. The documents are horrible with no clear instructions or up-to-date information. For the Plutus platform, Remix in Ethereum can easily code/test/deploy the contract to the testnet/mainnet, Plutus playground like a testing application in comparison.

I opened the issue to ask about the clear documentation but the response is the document is not the first priority now. This is not correct, the document affects whether developers will come in. The more developers in the environment, the more mature the system will be. Deciding to learn a new scope like blockchain is costly and risky for a developer, if the documentation is still like this, the developers will keep dropping and go to other chains that have better development experience.

As a full-time developer who all-in on Cardano, I believe in Cardano for the fundamental structure that is well-prepared and secured, but the system cannot sustain by only this. The amount of people is the key to the blockchain system.

4 Likes

Hi Eric
As a very first feedback on your request: yes we are aware.

Especially in the SPO area, a comprehensive reorganization is currently underway. Historical instructions are to be retained, but each with clear date and version information.
And yes some recent parts are missing.

However, the developer portal is also an open platform. Everyone can submit pull requests there if he wants to correct, add or rebuild something.

3 Likes

Appreciate for CF team’s response, I believe the easiest documentation is, the more developers there will be, causing the maturity of the developer portal. But the thing is, we need to lower the entry requirement.

2 Likes

That may be true in general but I can say from personal experience that there’s no entry requirement for contributing to the SPO documentation. Note the new branch of content below… I’ve merged a lot of this myself and I can confirm what @werkof said that anyone can contribute: any technical errors that editors see will be challenged and corrected in a cooperative and supportive review process :nerd_face:

Please @eric248550 & others, have a look at what we’ve done so far in the topic outline & SPO course specific branch, and feel free to assign a topic to yourself… I look forward to doing this with some topics when I get more free from review-oriented tasks :star_struck:

1 Like

As a new developer in Cardano, I couldn’t agree more.
I can’t imagine any develoer will be interested in join Cardano unless there’s huge benefit.
I’m worried this community would become a very small group.

This is an ongoing process, the developer is leaking to other chains right now. Even though we host some events and developer boot camps in our country, most developers step back because of the worst documentation.

Yes, there’s no entry requirement to contribute documentation, but you can’t expect all the documentation made by the community. This causes the developer of Cardano to become fewer and fewer.
If I’m a developer new to Cardano, I’ll step back when I saw the documentation is not up-to-date.

1 Like

Agree. @werkof should take this more seriously. Get it up the list of priorities.

Cardano now has everything except a healthy dose of developers. They are the last missing pieces of the puzzle before Cardano can become truly amazing. The fact that I am still here after months of horrible developer experience can attest to that.

Documentation and education should be from IOG or emurgo. After all, they are the ones who create the libraries. Without proper doc, developing is like a game of trial and error. Especially when you’re doing something no one has done before - no example.

As an aside, Plutus Playground is a dead-end. I wished somebody had told me before I wasted countless hours trying to make it work. It is buggy and now acting like a discontinued/unmaintained product. The fact that Plutus Pioneer Program uses this thing is a huge misdirection to new comers.

This link is my take posted weeks ago. With hindsight, it was not accurate/relevent on certain points but share the sentiment.

You are not alone

Understandable. Last month I was :pinching_hand: this close to go to Algorand.

Not every dev is as enthusiastic about Cardano as I am.

Yesterday I tried to find cardano playground for plutus learning, and noticed the playground SSL certificate has been expired.

https://playground.plutus.iohkdev.io/

With certificate expiration, even though I accept this certificate, the compilation still fails.

image

I tried to compile my own playground, and I noticed the plutus-playground has been completed removed!!! I traced back to the PR and there’s no description?

More than 20k lines of code has been deleted without any explaination in this Pull Request.

There’s no need to keep coming up with new features/concepts, if the basic knowledge keeps changing this group will finally become 10 people playground.

Plutus-playground has been removed because it’s no longer maintained by IOG

This makes the new Plutus developer worse, no communication with developers, and the technical discord group has no these announcements.
Furthermore, the newcomers spend plenty of time watch plutus-pioneer-program, to learn the tool that has been removed.

That is exactly the problem I’m facing!!!

Why doesn’t IOG maintain plutus-playground anymore? Is there a similiar tool for plutus developers to verify their scripts?

Just adding my my viewpoint between sites :

developers.cardano.org => Initiated by CF, but community maintained (if the ecosystem aims developers to only use the content and not give back, it is not gonna be sustainable regardless). So far, it has attracted some community projects, and started seeing collaboration from SPOs - but not as much from dApp developers to prepare guides. To me, this is more of a roll up your sleeves and add content independently as a community (be it as an org or as an individual).

docs.cardano.org => Primarily managed by IO (if we think there will be someone around forever to provide steps, might bet for this site and provide feedback there). In my experience - they’re usually not very active on socials. You’ve better luck against their github.

3 Likes

Dear All, please consider this from a professional. I have been developing software for 48 years now (YIKES! That’s right, almost 5 decades.) I still develop software. The absolute primary key (pun intended) for learning a new language is not how cool it is, not how elegant it is, not whether or not it is necessary to accomplish a task - but how much documentation there is and the quality of that documentation. Consider that Apple, back in the days when it was struggling as a company, focused on developing materials to support developers - in the (correct) mindset that supporting their developers would produce usable software, that everything on a computer is software (nobody cares about the hardware per se), and that more and better software would drive product adoption.

Since this seems to be a loose alliance of disparate individuals, it seems someone should lead the effort to develop better documentation - and that I believe would fall squarely into the Cardano leadership community and IOHK. Think about it - if the development is rich and rewarding, then more and better apps will be developed - driving adoption (and maybe luring developers away from other blockchains or other disciplines).

2 Likes