You read my mind. I've been keeping an eye on this project for a month waiting for the literature to improve to a place where I feel comfortable investing. It's not just a simpler setup or clearer instructions, it's providing information on the benefits and risks to an investor.


I know you're a tech guy but take a step back and look at the title of that page: Running-a-Yield-Generator. The page you need is "Guide for Investors". It should have:

• What is Joinmarket?
  
  A short (1-2 sentence) overview of what Joinmarket is and what it does.
  
  
• What is the role of investors in Joinmarket?
  
  A short (1-2 sentence) overview of the role of investors.
  
  
• What benefits can I expect as an investor?
  
  This section should be very specific and as long as it needs to be. Sure you can talk about market rates etc, but give concrete examples with reasonable rates. If I invest 100 BTC and set a rate of 0.03%, what will my profit be? At 0.1%? At 0.5%? A table listing various amounts and rates and transactions per day would work well here. You also need to talk about the volume of transactions, both currently and in the future. I know privacy is a part of the system so maybe you don't know precisely how much volume there is now but the bid/ask type messages are sent through IRC so you must have an estimate. 2 transactions a day? 20? 50? 1 BTC a day? 10? 100? And you can talk a little about the future potential to entice investors.
  
  
• What risks are there to investors?
  
  You said something about risks from bugs in the software. That and any other risks need to be detailed here in very specific form. Which software having bugs will cause a loss? Just Joinmarket's local python app or other parts of the system? How could malicious participants affect the system? And what would the loss be: all of the BTC in Bitcoin Core, or just those in the Joinmarket wallet, or full system compromise? What can investors do to mitigate the risks?
  
  
• What is the yield generator and how does it work?
  
  Explain the role of the yield generator and very specifically how it works. How is it funded? [not command lines just an overview of the process] What funds does it have access to? How and why does it communicate with Bitcoin Core? How does it communicate with other participants? What kind of "offers" does it put out to the marketplace? How does that relate to the total BTC the investor makes available? What exactly happens when an "offer" is "accepted"? [what are the actual steps involved in the coinjoin, from the perspective of the investor and their yield generator. Not technical details like pubscripts or anything, just the high level steps.] What happens when the coinjoin is done? What is the state of the wallet? Explain how the investor receives their profit. What about when the next offer is accepted? Is that different from the first one? How are coins moved through the different wallet levels? How does that affect the max amount the investor can offer? In essence an explanation of the life cycle of the yield generator through time. Also an explanation of how the investor monitors what the yield generator is doing. What offers is it making? Which did it accept? How can I see what my volume and profit have been so far? [not command lines just explain what information can be seen]
  
  
• What options can I configure for the yield generator?
  
  Talk about whatever the options are: rate, min/max amounts, transaction fees. What if I want to make multiple offers with different amounts and rates? [not command lines or names of variables just a high level explanation]
  
  
• How do I become an investor?
  
  This has two parts. First an overview of the process: requirements, an explanation of how the yield generator will communicate with Bitcoin Core, any other high level explanations. Second the steps to get it up and running. This is the first place command lines or variable names should be used. This should include step by step every action needed to become an investor. It's not ok to say "You also have to understand and follow all the steps on these two other pages" like the yield generator page does now. All the necessary steps should be right here. Obviously you don't need to explain how to install Bitcoin Core or anything super basic that any investor would know but it's better to be on the side of listing too much instead of too little. For example if Bitcoin Core needs to be set up for RPC, the steps for that should be explained. If I follow all of the steps here I should be able to go from an empty user account to being an investor in Joinmarket and (hopefully) making a profit.
  
  
• How do I monitor my activity and profits?
  
  Command lines of everything an investor needs to know to view and understand their activity over time. What offers is the yield generator making? Which did it accept? How can I see what my volume and profit have been so far? How can I see other offers in the market? How can I see what "counteroffers" takers made? How can I see which were accepted? This type of transparency is necessary not only for the investor but for the network too. How can an investor adjust their offers if they don't know what the other side has been "counteroffering" and which offers have been accepted? Also include instructions for how to update to the latest version of the software on a regular basis.