Results Of The Documentation Survey

Discussion in 'Incubator' started by gratefulcheddar, Apr 11, 2017.

  1. 2017/12/15 - Decred v1.1.2 released! → Release Notes  → Downloads
  1. gratefulcheddar

    gratefulcheddar New Member

    Jan 9, 2017
    12
    5
    Male
    CS Student
    IL
    This is going to be a very long post. As many of you know, I created a survey to collect some feedback on our documentation. I’d like to thank everyone who participated. There were a total of 75 entries after 3 days with 70 people leaving their DCR addresses for the raffle. For selecting a winner, I built a Ruby script to select the winning address randomly. The winner of the 5 DCR prize is DsVUqgsFk4GiCw6FLcG9YEVTpQyKnWYew4D, TXID: cf44cd0b7ea7279dcd8ea9df8c5a60c266d8ce9faaaf179f2adb12b5de7b97d4. Congratulations!

    I’ve sorted through all of the answers and have listed a majority of them below.

    There may be answers here that we already have in the documentation. I’ve still included these answers as this might allude to the problem of it being too difficult to find said information/guide.

    I realize that some of these questions might have been a little redundant. There are a lot of answers that are present in multiple questions.


    1) What information do you feel is missing from the current documentation?
    1. Needs to be more user friendly (we need both technical and non-technical documentation).
    2. How to add a public passphrase after the wallet has already been created.
    3. dcrstats API
    4. More information about the currency (opposed to how-tos/guides).
    5. POS Mining (more precise information), comprehensive).
    6. How to contribute and get involved
    7. The mechanism for how the developer money gets distributed.
    8. More in-depth information on the individual topics for advanced users.
    9. Vision of the future, “The future”
    10. More clear info about the coin mining curve, including PoS vs PoW
    11. Use cases
    12. Comparisons to other top cryptos, differences of currencies and merits of DCR
    13. Raspberry Pi tutorials (staking, setup)
    14. gominer linux guide
    15. Deprecated commands and their replacements
    16. Unsupported commands still present in dcrctl -l (“move”)
    17. Transparency stuff, finances
    18. Information about hard fork voting
    19. How to upgrade to a new version
    20. More pictures
    21. Roadmap
    22. Block time, max supply, reward forecast
    23. Dating the updates
    24. News section
    25. Solo PoW mining
    26. OTC tutorials for dummies?
    27. Updating paymetheus
    28. Better menu hierarchy for “Download and Install”
    29. Explanation of fees
    30. Decred API
    31. “decentralized credits” isn’t mentioned anywhere
    32. “For the sake of this survey I am only going through the first section of the Getting Started Section. From what I see the Beginner's Guide could use the most work. At best EARLY on it can give an overview of how Decred works conceptually. It claims to not overwhelm in the first paragraph by using overwhelming examples. At least there needs to be a link to an overview of what cryptocurrency is and then how decred works within the construct of that. There are a few good guides that could be linked to that I know of. After that jumping immediately into the applications and how to install them is abrupt. While the applications are important, it is daunting for someone who is still deciding whether or not they are willing to install yet. This second paragraph could use a good punch up to once again not use so many concepts that are still outside the vocabulary of a new user. What I am suggesting is giving an overview of how/why Decred is great. A little bit of history, a little bit of the idea of how the wallet works, and a reminder that it is all contained in the block chain. Just enough to get someone interested enough in the ideas underlying decred to want to install. I think it is fair to assume a lot of people will see these first few paragraphs who have absolutely no idea how any cryptocurrency works. This may be the first introduction to the viewer outside of hearing about it or reading an article.”
    33. “Information relating to errors and explaining the details of what is actually happening. For example, while I was trying to set up my Paymetheus wallet by following the instructions listed in the docs, ( see my which pages improved upon link ) it was asking me to connect to a dcrd RPC server, which was explained as a communications tool for dcr network, which I did like. But the information was pre-populated and I am no security expert, but I went ahead and clicked continue anyways. After which, my wallet kept crashing after syncing the blockchain, so I had to refer to support-pos slack. In short, I would like to see more frequently experienced issues/errors”
    34. “Newbie friendly information, for those who never heard about cryptocurrency or deCred before. Informations like how you could store money in a paper wallet, how safety it is compared to banks,etc. Payment gateways for those who have online stores. Lightning Network for newbies, and how fast online transactions can get through.”
    35. “Perhaps a general warning, informing, educating crypto noobs about the risks of sending DCR to people who know your private key. There are new people in the crypto space every day, and many people didn't live through the Mt Gox catastrophe. For example, Evolution is a cool project, but I think many are so infatuated with the prospect of making money that they don't realize that they are trusting someone else to hold their money for them. Obviously, if they know the risks and proceed, that's their right and choice. I'd just hate for the project so early on to get plagued by really smart people preying on the naive.”
    36. “Security when staking: I had a really hard time wrapping my head around how to do this as a solo miner or even with a pool. e.g. how to setup hot/cold wallets, why should I create a separate account and not a separate wallet for voting, how delegated voting with cold wallets actually works, what is the purpose of the redemption script, coin recovery when dealing with tickets, and coin flow for ticket purchasing.”
    37. “Technical details, e.g. how is a Decred Address formed (see for example https://en.bitcoin.it/wiki/Technical_background_of_version_1_Bitcoin_addresses), what are the outputs in a stake transmission and so on. But this might be better for later, since you should focus on normal users for now (as you are doing). Developers can in the meantime look at the sourcecode.”
    38. “It’s hard to understand the difference and meaning of Proof of Work and Proof of Stake. How do I show proof of stake? Ideas and concepts like this need to be distilled to just a few sentences, not paragraphs. You need to help the "average" person understand this so they understand what they're getting into, but easily. Although the "Proof of Work" section says "As you can see, it's quite simple", the next thing it does is list a 9-step process with a lot of jargon. Why would a user want to vote on a PoW block? What does it mean to vote? Do I go to a website to vote? It's a hard concept to understand. This is something that I, personally, see as a huge barrier to new people.”
    39. “We’re missing a lot about PoS. This is why I haven't started yet. Although some guys tried to put a tutorial together it is mainly for Windows (I use a Mac).”
    40. “Use of plain English in the writing. Description of why ticket fees can be high or low and links to recommended tools that show the the ticket price - fees = potential return on a ticket based on length of the window and number of tickets in the mempool. A good description in visual flowchart format of the end to end process in staking, the price dynamic between pow miners and pos stakers - what the factors are that drive the ticket price and fees up, when and why to set a low or high expiry in relation to the ticket, the impact of the number of tickets in mempool - then what the formula or factors are in the tickets voting or not and why a ticket is missed.”

    2) What pages would you like to see added to the documentation:
    1. Technical: How to connect to wallet/daemon via Javascript
    2. “Why Decred?” in the beginner’s guide. Why invest
    3. Pages with print screen (screenshots)
    4. Paper wallet using CoPay Decred web wallet
    5. How to accept Decred as a payment method for businesses
    6. How Decred can be a payment network
    7. Decred as being to first coin with Lightning network and how it can revolutionize the crypto world, allowing millions of transactions per second.
    8. Running CLI wallet on VPA
    9. —wallet commands
    10. Understanding ticket fee/cost fluctuation
    11. Information around ticket price, what it is, why its higher or lower, the avg, min/max, etc
    12. A complete list of pool mining sites
    13. Proposals: setup/creation, propagation, voting.
    14. Installing/configuring an unattended PoS/PoW setup.
    15. Video links, videos
    16. Decred history, origin story.
    17. Dev team creation history
    18. Official events
    19. Marketing campaign
    20. Roadmap
    21. Recovery in case your coins get lost
    22. Security
    23. Official sites who support/use Decred
    24. Voting only wallet guide
    25. Step-by-step buying tickets at good price
    26. Glossary
    27. Guide on minimizing fees
    28. Decred vs. Others
    29. Color
    30. Where to spend DCR
    31. Upgrading
    32. Raspberry Pi
    33. Decrediton documentation
    34. Integrations with other platforms (like holytransaction)
    35. Business plan, projections
    36. Promotions
    37. More about PoS and PoW
    38. Full Node information
    39. Most frequent wallet errors
    40. SGMiner
    41. “I think you have all the right information here, but I think organization could always use improvement as well as continuing to expand on them for the average user, I am personally a huge fan of FAQ and would move it further up the left-hand column, but I also see that you are trying to create a step-by-step flow.“
    42. “Better detail on the dcrwallet.conf settings, especially ticket buyer config. Many of the settings don't seem to work as documented, maybe it's a documentation misunderstanding, like the fee multiplier for examples and median/mean fee calculation.”
    43. “I would like to see a more exhaustive introduction. In particular, for those who come to Decred straight away, a more in depth explanation about bitcoin itself, which ends by presenting it's main problems. This will set an even better stage to make the advantages of Decred shine in my opinion.”
    44. “Not pages per se, so much as better explanations and examples. Don't talk about crazy distributions and stuff, just say "Hey, if you put in X DCR, here's what happens.””
    45. “A list of the programs included in the installation and what the purpose of each is - its confusing to understand the A1:G77 betwee the decred windows gui and paymetheus standalone and dcrd which needs to run in the background.”

    3) What pages would you like to see improved upon? (If your answer didn’t include a current page or a specific improvement, I combined it into question 1 or 2 above)
    1. Beginner’s guide (multiple answers)
    2. “Mostly the Getting Started Section. I have notes on almost every page, but at this point what the community needs is exactly what someone said in chat months ago and again on 4/5/17. To paraphrase, "It needs to be accessible to new people and understandable by people who aren't tech savy.””
    3. Translations
    4. Paymetheus download/install page
    5. Gominer windows guide
    6. Screenshots/example in setup guides, separate setup pages more clearly by OS
    7. Proof-of-Stake guide (MANY ANSWERS)
    8. Glossary
    9. Configuration file options
    10. Improvements to the docs site design
    11. Social media links in About section
    12. Download/Install page (add RPi)
    13. Proof-of-Stake guide - details on monitoring tickets
    14. Voting (multiple answers)
    15. “Plenty of the phrasing used throughout the docs is redundant, poorly structured or needlessly complicated. I will propose alternatives through Github, which Karamble is teaching me how to do this week.”
    16. Expand Advanced dcrctl Usage page
    17. Proof-of-Work pages
    18. Proof-of-Stake pages - details on hardware and infrastructure requirements
    19. Every page - its just boring texts
    20. Compiling from source
    21. More newbie-friendly in general
    22. Common errors and solutions
    23. FAQ
    24. gominer
    25. PoS docs are scattered and outdated
    26. Navigation font
    27. Adding visual diagrams

    4) What video tutorials, if any, do you think would be most beneficial?
    1. Explanation of Decred
    2. Use cases
    3. PoS mining (MANY ANSWERS)
    4. “How to make your wallet as safe as possible?”
    5. “The focus should NOT be on making a tutorial on how to setup software on wallet, work mining, or stake mining. Decred right now would benefit most by creating more well produced exapnded versions of the topics shown in the "Decred Intro" posted on YouTube by D3C RED. Basically take the things in the powerpoint presentations and make it look pretty and put music to it. Explain the bullet points in more detail.”
    6. Explaining advantages of governance
    7. PoW mining, all software
    8. Using CLI
    9. CLI Installation
    10. Getting started with Web Wallet
    11. Jordan Peterson
    12. Voting
    13. How to buy DCR
    14. Coinbase presentation
    15. Promo videos
    16. Updating software
    17. Using Paymetheus/Decrediton
    18. Raspberry Pi
    19. Wallet Management in CLI
    20. Tutorials like Ethereum’s

    5) Any other feedback/suggestions/comments/concerns?
    1. “More PR, it’s a very promising project but mainly unknown and a little bit complex for the noob.”
    2. “No, just to make decred as friendly as possible to newcomers.”
    3. “I would consider an experiment where you try to get an average user to get a dcr wallet up and running by themselves following your guide and see what kind of pitfalls or issues they have getting the basics going.”
    4. “Some people I know do NOT like the name decred, while its amazing tech non techy people need something with a good name. Do a better job explaining why decred.”
    5. “Your docs are outstanding, really well done! Focus on how decred as a system works, I needed to watch the talk you guys gave at coinbase to understand it all”
    6. “Maintain detailed release notes and upgrade guides with new releases (highlight configuration and behavioral changes of a new release)”
    7. “yes, please start using medium blog more often. example: https://medium.com/@luisfernandomolina"
    8. “Yes. The development of a payments gateway with fiat currecies and partnership in create a Decred Debit Card with flags as Mastercard or Visa. With Decred more "useful" the comerce will aprove it and add value to crypto.”
    9. Yes, an explanatory video for PoS and PoW
    10. “I don't like POS pools in general since most of the fees paid to pools are being dumped by the owners straight away (https://twitter.com/Sicarious_/status/845936754720935936) I also don't like docs part where they seem to be encouraging to use pools. My suggestion to the project would be to drop POS pools completely and keep POS to buyers by also getting rid of that stupid requirement to keep the wallet online, there must be a solution to avoid that.”
    11. “I had a pretty hard time getting started with the voting process and I think it is one of the main draws to a system like Dcred. Simplifying this information might go a long way towards growing the ecosystem. The documentation, while excellent, felt disjointed. A single page with most of the details required to understand and run Dcred would be useful.”
    12. “For those parts that I have used and read, apart from some of the phrasing, I think an amazing job has been done already. I hope to be able to participate with the French section.”
    13. “a better way to get some decred would be nice =D”
    14. “Improve marketing presence”
    15. “Please document somewhere your decentralization roadmap and contingency plan. Your plan for increasing bus factor, or if big brother asks to cooperate.”
    16. “A little lost how the vote consensus thing will work out, looking forward to know more.”
    17. “Would be great an Integration with Ledger Nano S, and Android App”
    18. “Would love to see a tutorial of POS on a Raspberry Pi :).”
    19. “Is it possible to change the language of the wallet Win64”
    20. “I think that images/prints/charts are the best. Everyone when its looking to some magazine (whatever) is going to look for the images first, they (kind of) introduces the users to what the author is thinking about. Not that is feels missing in the docs, but I think it's very important when walking about Wallets, because its the most important thing, and even non-programmers will read that, and for them you have to do the simplest thing.”
    21. “It's a great coin so far, and I hope it keeps growing! Making it easier to buy it would be helpful, too.”
    22. “It might be a translation page where people from around the world would help to translate from English to another language.”
    23. “Need more marketing online, like Dash”
    24. “Translate the guide to other languages(portuguese, spanish, etc).”
    25. “Creation of wallet for iphone.”
    26. “All videos must be with english subtitles. Because we can use it for translation to portugese.”
    27. “Segwit?? “
    28. “In my opinion, the fact that DCR recommends the owner of Evolution as a good pool for PoS mining, people think that you also recommend Evolution. It's being caused some misunderstandings. “
    29. “Have a balance option in usd on paymetheus"
    30. “there not enough Devices(information) for getting interested”
    31. “for me this documentation until now is really beneficial. There are for shure things that can be optimized, for me it is a good guide and a good way to start. “
    32. “I've seen people talking a lot of shit about Decred, like "it sucks because of this decentralization", or "imagine gold having governance, people being asked to vote if it should not be a metal anymore"... stuff like that. I think most of the traders and holders don't know what governance is and probably we should dive into this subject later, to show the difference from Bitcoin.”
    33. “People are still afraid of what's new to them, but it's up to you through good marketing to show them how life can become more practical.”
    34. “The project is wonderful I am very enthusiastic the whole team of devs and the community are congratulations for building a beautiful project like this.”
    35. “What are the advantages of Decred over other cryptocurrencies?”
    36. “a lot of your docs which are wordy and use complex language can be replaced with videos and a super easy UI for the wallet.”
     
    Tivra likes this.
  2. jcv

    jcv Full Member
    Developer

    That is a lot of feedback. Good to see. I might have to wait until tomorrow when I can actually take the time to read it carefully before I can start thinking about what is in there. Thanks to everyone who contributed!
     
    Tivra likes this.
  3. ClokworkGremlin

    ClokworkGremlin Sr. Member

    Jan 10, 2016
    535
    381
    Male
    Whatever I want.
    I think the lack of a paper wallet and something in the Android app store (I don't use iOS, but an iOS wallet app would be good, too) is probably hurting Decred's growth. I'm actually surprised nobody's set up a paper wallet generator yet, I chatted with someone a year ago who had address generation working in Javascript.

    On the Raspberry Pi topic, I'm actually planning on revising my tutorial to warn that the blockchain is likely to break 32GB within the next year or two(based on very loose estimates on my system). When this happens, the Raspberry Pi will no longer be as feasible an option for POS mining due to poor external hard drive support. Personally, I will be upgrading to an inexpensive x86 machine near the middle of the year to take advantage of faster processor speeds, higher memory, and larger internal storage, all of which will both improve catch-up rate for the initial synchronization, and likely reduce ticket misses.
     
    Tivra likes this.
  4. jcv

    jcv Full Member
    Developer

    As for the raspberry pi, I'm pretty sure they support the 64GB sd cards. Not sure how you got your 32GB estimate in a year or two though. For mainnet, I currently see:
    Code:
    jcv@triforce ~ $ du -sh .dcrd/data/mainnet/
    1.4G   .dcrd/data/mainnet/
    
    So I think we have some time left while the rpi is still useful. I have seen instability on them thermally when pushed (at least on the 2s) but dcrd probably shouldn't push it too far.
     
  5. ClokworkGremlin

    ClokworkGremlin Sr. Member

    Jan 10, 2016
    535
    381
    Male
    Whatever I want.
    64GB card support is poor, and synchronization would take weeks if it became necessary. I looked at the free space on mine and it was at 16GB, Very loose estimates.
     
  6. davecgh

    davecgh Hero Member
    Developer Organizer

    Dec 31, 2015
    642
    788
    Male
    United States
    It's not on the roadmap at the moment, but it is completely possible to implement pruning in dcrd which will significantly lower the disk space requirements.
     
    ClokworkGremlin likes this.
  7. ClokworkGremlin

    ClokworkGremlin Sr. Member

    Jan 10, 2016
    535
    381
    Male
    Whatever I want.
    I think that, so long as it doesn't pose a risk to coins in cold-storage, a pruning/snapshotting system is going to be key for more widespread cryptocurrency adoption.
     
  8. Shadowlance

    Shadowlance Full Member

    Jan 9, 2016
    220
    155
    Male
    On a couple of these points:

    “In my opinion, the fact that DCR recommends the owner of Evolution as a good pool for PoS mining, people think that you also recommend Evolution. It's being caused some misunderstandings. “

    I've seen this happen a few times in Slack, and it's a valid point. I know Dyrk isn't plugging evolution or dcrstats as official tools, but the close coupling with dcrstats and the pool, which are both promoted in official channels does make it understandable that people link them all together as being part of Decred. Maybe there needs to be a disclaimer on all of our (personal) sites that they are personal and not part of the official Decred ecosystem.

    “I don't like POS pools in general since most of the fees paid to pools are being dumped by the owners straight away (https://twitter.com/Sicarious_/status/845936754720935936) I also don't like docs part where they seem to be encouraging to use pools. My suggestion to the project would be to drop POS pools completely and keep POS to buyers by also getting rid of that stupid requirement to keep the wallet online, there must be a solution to avoid that.”

    Here, we're basically paying someone to boost another coin while putting sell pressure on ours. I know people can use their pool funds for whatever they want, but I don't think it should be on the official list, especially since they openly say that's what they're doing. I know the devs have taken the (commendable) position that they're not interested in the price, but a lot of people are, and they judge the success of a coin by its market cap. We don't want to openly subsidise downward pressure on the coin.
     
  9. jcv

    jcv Full Member
    Developer

    I'm finally going to try and move most of these over to the github issues for docs where we can figure out which to work on, discuss others, etc. It is a lot so it will take some time but they will all be under the label Survey-reults:

    https://github.com/decred/dcrdocs/labels/Survey-results
     

Share This Page