Closed gracegui43 closed 5 years ago
@lock9 have a lot of experience in this
Hello,
My experience is mostly in product development and in this area, we always start thinking about our "customer". Who is him/her, what are they looking for, etc. Using answers from these questions we can create something that people actually want.
Here is something I did when thinking about the documentation, but could be "applied" to another area (sorry for the terrible colors, I'm not a designer):
I would suggest trying to understand who is the customer we want to reach, what do they want and build a portal based on these answers. In the image, I only considered "developers", if you are looking to build a complete NEO portal, I would add some extra "customers" to that list like investors and government employees (and also rewrite all the columns).
Extra note: Thinking about customers is not very easy, it would be good to interview a few of "them" to understand "what are they looking for".
I'm not sure if I can understand the scope of this portal. Should we care to explain parts of the code that they are not going to interact with? In other words: Is it aimed for "developers only" or is it going to include technical aspects that are relevant but not directly used by the developers?
I think at this stage, developers are our main customers with highest priority. So we can have the page for developers only. And the other portal can be designed in different pages.
Hello Grace, Are we considering what kind of developers? C# only? With or without previous blockchain experience? Should we care about exchange developers?
Maybe we can divide the "developers" into smaller groups? 🤔
It's a good question. Personally I think different language support is our advantage and language can be used as a reason for grouping. However, it may be hard to maintain different language tools. So maybe we can list C# page first since it may be more complete, and use C# as a template. Then we list the other language such as python and javascript, and expand its content.
I did this structure in the past:
NEO DOCS
About NEO
NEO
NEO Foundation
NGD - NEO Global Development
NGC - NEO Global Capital
NEO Technology
Consensus Mechanism
Consensus Whitepaper
Consensus Diagram
Whitepaper
Network Components
Consensus Nodes
Relay Nodes
Light Wallets
NEO 3.0
NEO Virtual Machine
NEO Enhancement Proposal (NEP)
NEO Community
NEO Research
New Econo Lab (NEL)
City of Zion (CoZ)
(Add other)
Blockchain Development
Using the SDK
C#
Python
GO
Using RPC (HTTP)
Asset Transfer
NEO
GAS
NEP-5
Fees
Network fees
System fees
Hosting a private chain
Configuration Files
Wallet file
Wallet representation
NEO Plugins
Advanced Topics
Network Protocol
Transaction Serialization
Contract Transaction
Invocation Transaction
Smart Contract deployment
Oracles
Using the wallet through RPC
Document for Exchange Developers
Version 2.9.2
Version 2.9.1
Version 2.9.0
Version 2.8.0
Version 2.7.6
Blockchain Explorers
Network Monitoring
CoZ Monitor
Happy Nodes
Notification Server
Smart Contract Development
Setting up your development environment
Local network
neo-local
Using the debugger
C#
Python
Smart Contract Basics
Supported types
Boolean, byte, integer, string, array, map
Authentication
Check Witness
Verify Signature
Multisignature Contracts
Storage
Contract Triggers
Hash functions
Random numbers
Serialization
Fees
System Fees
Network Fees
Object Serialization
Deploying your smart contract
Invoking a smart contract
Retrieving notifications
Samples and Tutorials
Hello World
C#
Python
Lock Contract
Domain (Domain Name System)
Contract Authentication Tutorial
Deploying a Lock Contract
Custom token (NEP-5)
API Reference
Unit Testing
NEO .NET Dev Pack
Downloads
Executables
NEO-cli
NEO-gui
Neon
Configuration files
Blockchain files
In another study(incomplete and unordered), I gathered these results:
"Code level topics"
--
RPC
Indexer
Off-chain
'sendrawtransaction',
Multi-signing
Transaction Status
2 token model
Network Protocol
Data model (including protocol messages)
Binary serialization
Json Encoding
Security
Consensus
Gas generation
Gas claim
UTXO
Gaming
SDKs
Patterns
Fees
Network fee
System fee
Transaction building
Attaching gas
NEP-5 transactions
Multiple NEP-5 in one transaction
DEX
Quantum protection [NEP-85](https://github.com/neo-project/proposals/issues/85)
Smart Contract
API
Patterns
Docs
Unit Testing
Debugging
Examples
Neo-local
Components
Security aspects
Private key generation
Encrypted private key (nep-2)
Wallet
Light Wallet
Indexer dependency
Code patterns
Neon
Wallet (Node)
Neo-cli
Code patterns
Plugins
RPC
RPC security
NEP-6
(Decentralized )Exchange Developers
Security
Patterns
NEP-5 tokens
Game tokens
Other tokens
Decentralization
Elections
Node geo-location
Consensus
Single block required (I don't remember the correct term)
15 second confirmation time
NEO 3.0
Unfortunately, I used the wrong persona in this study, but I think I can rework it to consider C# developers "only". We have to be very careful how we design it, because if we present it too much "Windows with Visual Studio"(common C# tools) it can make developers from other programming languages and platforms to lose interest. Also, Neon wallet is (in my opinion) a masterpiece and it is entirely made with javascript, I'm certain that developers can learn a lot from it (even if they are not interested in making a wallet).
I like a lot your table diagram Ricardo. One thing we lack for developers is a Neo Unified Development API. This could be a table embedding all existing features, from basic to advanced, for example: TOPIC. LANGUAGE. EXAMPLE. IMPORTS Put data on storage. C# Storage.Put("Hello", "World"); using Neo.SmartContract.Framework; Python xxxxxxxx Something like that,organized by sections of broader topics, in a very clean way. Perhaps, it could include a "link to complete example", in neo/examples (or elsewhere), and have includes on hidden bullets (language could be selected too). But I still like two main views (perhaps with different background colors): (1) for users / investors / entusiasts. (2) Neo developers
Core dev is outside the scope,more related to yellowpaper and github issues / pr.
@igormcoelho Thanks. Correct me if I'm wrong: I think that what you are saying is that we need to split into different abstraction levels. Is that right? We need to define what abstraction levels we want. I suggest we use UML for that (different diagrams for different abstraction levels).
For "code level help" (API/SDK), I think we can use "tabs" for each programming language. This means that the explanation is programming language agnostic, but the examples are shown in C#, Python, Go, Typescript and Java.
To avoid us "waiting" or "depending on other people" we could start with C# only. Instead of using "least common multiple" we use the most complete one. I "changed my mind" because in my 'main area' (app development) we never choose tools that offer the least common multiple because this has a very high impact in the resulting software (fewer features, less performance), so yeah, maybe we should focus in C# ('.NET core') and add other things later on. We don't have any examples of light wallets done in C# but we have neo-modules that can be used for that purpose.
TL;DR: Use UML Use tabs in code level examples Focus in C#
I did this structure in the past:
Hi Rick, the structure is nice! But it is more like documentation structure, right? If for developer portal design, can you suggest a simpler version?
I think for a developer there are only three necessary sections to get started
For beginner this will get you 90% of the way there when working with NEO. Once you get past these three topics you can get into more advanced topics like those written out in full by @lock9
Hello people, Is the discussion going to continue here? Can we close this and continue in discord? @Grace-Gui it is up to you, if you want to keep it open, we can keep it open.
We can close it. We will update the developer page in Oct. Thanks for all the suggestions.
Currently we lack a unified portal to showcase infrastructure and development tools, which may be inconvenient for developers. If we can have a developer portal page on the NEO official website, what should be included and how to design?