How good are our docs, and how would you improve them?

Hey you all! I’ve seen many new members who are also new to the smart contract development scene (thinking of you @RockmanR, @abcoathup, @frederickalcantara, @drakon, @dulce and @Bleier) and we could really use your feedback (any everyone else’s) to improve our guides and documentation (OpenZeppelin, ZeppelinOS) both on our products and on general development

  1. What guides did you find useful the most?
  2. Which ones you think are missing?
1 Like

@martriay, I’m still reading through the documentation. A little slower than I had hoped. Still have to run the business while continuing to learn. I plan to offer feedback to the group as it’s the least I could do to help others.

I will say, as a newbie, that one of the most difficult concepts to grasp is the overall structure of what constitutes a dApp. From a 10,000 foot perspective, it looks like you mint a token and you’re in business but when you delve into the process you find out that there are many nuances in the development of the dApp. The minting of the token is just a small piece of the puzzle.

I think a good place to add value would be a step-by-step guide to smart contract development or maybe some links to recommended reading for newcomers. I first read The Hitchhiker’s Guide to Smart Contracts in Ethereum by @maraoz. It contained good information but the contracts need to be updated again for Solidity 0.5.0+ as I had trouble with execution of some of them. Ib particular, with the ‘constant’ word as it has been deprecated and replaced by the ‘view’ word.

Finally, I think a point of confusion for me in the beginning but one that I now understand better is that the complete dApp doesn’t have to run completely on the blockchain. There is a local component of say, web apps in JS or PHP with some DB storage and only the open chain transactions need to be stored on the blockchain. It took some reading to figure this out. This could be more clear in a tutorial.

More to come as I read through more guides.


My first suggestion to the guides is to make them more formal. I would suggest something along the lines of a basic tutorial to walk you through the basics of starting a smart contract with zos & Open Zeppelin. Look at this Example, this is a good example of what could be done. Along with some reading articles to help beginners and those who are not familiar with smart contract dev learn more. See this Example, a page dedicated to this.

1 Like

My feedback is to make the ‘sample deployment’ guides less dependent on other development tools and languages as possible. For example, less java script and deployment frameworks.

Its been a year since my first interaction with zeppelin contracts and their guides. I have learned a lot from zeppelin but then faced many obstacles due to my limited knowledge in software development in general. Part of them relates to: contract deployments and contract UI. The sad part in learning solidity is the dependency on many environments that relates to Javascript and web development. I’ve started learning solidity using remix environment, then faced issues deploying zeppelin contracts and thought that the only way to move forward is to start learning about truffle. truffle was overwhelming due to the asyc functions, which were very new concept to me. So i’ve start learning Javascript to understand the asycs. truffle terminal was still complex to deal with, so i’ve used truffle boxes samples to interact with my contracts using a web page. But that opened a many gates for confusion, I couldn’t understand the architecture and the clear line that differentiates between: web3js, light nodes, front-ends, back-ends, and APIs. So I went to a course on Full stack web development in Udemy, just to eliminate obstacles in learning smart contracts. Now I’m back to smart contracts & zeppelin, and I can feel that I’m better prepared to handle more complex deployments.

The question is, does everybody needs to have a web3js (or other framework), java script or web development background to develop smart contracts seamlessly? In my opinion, They shouldn’t need to. I recently knew that I didn’t need to move out from remix to deploy zeppelin’s crowdsale samples, and build complex contracts. I’ve solved my issues with remix and I’m back building with it, away from dev environment noise. remix gives us the chance to focus on solidity and contracts development.

I see those 4 are separate domain of focus when developing a smart contract or a dapp:

  1. contract development, which include:

    • solidity language
    • contract hierarchies and modularity
    • contract interactions
    • contract security & best practices
  2. contract deployment, which include:

    • how to deploy contracts in general
    • sample deployment with common frameworks (truffle, embark, etc)
  3. contract interaction/interface, which include:

    • web3js and other frameworks role in contract interactions
    • samples on contract interaction (truffle terminal, remix, MEW, etc)
  4. contracts & Dapps architecture, which include:

    • contracts architecture
    • how smart contracts fit with the overall dapp and web2.0 architecture.
    • samples on different dapp architectures, based on use case.

While all the areas are important, I see that the most valuable to beginners and people who wants to focus on smart contracts are 1 and 4.

So I hope to see guides that are deployed with remix (or other tools if available) to reduce the noise of dev environments, and focus more on understanding the contract functionality/capability.

I hope this will help, and I’m happy to clarify any point.

thank you all,


I agree about understanding the dapp architecture. this is one of the most confusing part that let me to learn web development: front-end, back-end, and databases. now I have a better picture but would like to hear expert views on them. I still couldn’t find much people talk about it. from my current understanding, we are highly dependent on web2.0 to make use out of the smart contracts.

@RockmanR thank you for describing the issues so well. I haven’t had the opportunity to learn all of the various development components so couldn’t articulate the issues that you describe. I guess I could sum up my opinion as thus…

Zeppelin has developed the core foundation of contracts. If they could take the logical next step and build a plugin structure for building dApps similar to how Wordpress gives you a basic web deployment structure and then you can customize it with themes and plugins. This would really open up the dApp development space to people, such as myself, that have deep business knowledge but rudimentary software development skills. In other words, I know what I want to build but I’m stuck on the coding. I’ve built the website (using Wordpress) but now I need to build the token and dApp logic and I’m clueless where to start. At best, all I can do is read and hope I grasp the fundamentals.

If anyone is interested, here’s a link to our website… And, if anyone has some spare time to take on a side job, we have a set aside of ownership tokens for devs.

Hi @drakon. what I meant is actually the opposite. My view is to keep zeppelin focused on their core business/objective: developing best/secured standards to of smart contract library. One way to do that is to use the simple IDEs (like remix) to avoid topics on deployment tools (truffle) and JS interaction tools (web3js). This will give them chance to focus more into explaining the logic of smart contracts, their security, data flow, the hierarchy and modularity of them, and the use-cases.

I’m not sure if I am making sense :stuck_out_tongue:

@RockmanR, Don’t worry, you’re making perfect sense. I understand the point you’re making. While I’m not a software engineer, I’ve been involved in the tech industry for 40 years. I have observed and participated in three tech ‘next new things’ prior to blockchain. In all cases and as will be the case with smart contracts and blockchain in general, there will be a migration toward widgetizing the development process. I’m not arguing philosophically whether or not this is good or bad. I’m stating the point that in order for mass adoption of a technology to take place, it needs to become readily usable by the non-technical user base.

I took my first C programming class in 1984 after failing miserably with IBM 360 assembly in 1976. I learned real quick that I sucked at it too and concluded that I will never be a software engineer. At that time, mentors and friends of mine could bang out C code like typing a letter to mom. It wasn’t until IDE’s came along with C++ that coding visual interfaces became mainstream. The rest is history for the proliferation of so many languages. IDE’s were the sea change moment.

So, my simple, albeit long winded, point is that Solidity and smart contract development will follow the same path toward mass adoption. Zeppelin has taken a big first step by developing and then open sourcing the core set of contracts that everyone can use to standardize certain financial structures. Building upon that, they could take the first step to wigitizing the development of smart contracts and opening that aspect up to more business people and less software engineers. I don’t think that this detracts from their core mission as you stated. I believe it augments it and makes them a stronger partner to everyone that wants to move their business in the blockchain direction.

I, myself, am greatly appreciative of what they have done to present the community with real useable audited foundational code.

Thank you for this Zeppelin! Following in your footsteps, whatever we’re able to develop will also be opensource! I’m a firm believer in opensource code sharing. and have argued the case for it in many companies.