Make docs clearer

docs/frequently-asked-questions.rst

@@ -2,51 +2,55 @@
 Frequently Asked Questions
 ###########################
 
-What's the purpose of BTC Relay?
+What's the simplest explanation of BTC Relay?
 =============================
 
-To allow users to pay with Bitcoin to use Ethereum.
-
-
-Who is BTC Relay for?
-=============================
-
-Developers who want to allow their users to pay with Bitcoin to use their Ethereum
-application.
+It allows users to pay with Bitcoin to use Ethereum.
 
 
 How to use BTC Relay?
 =============================
 
-If you're a user, you should not need to use BTC Relay directly since it Workshop
+If you're a user, you should not need to use BTC Relay directly since it works
 behind the scenes.
 
 If you're a developer, did you see `How to use BTC Relay?
 <https://github.com/ethereum/btcrelay/tree/master#how-to-use-btc-relay>`_
 
 
+Who is BTC Relay for?
+=============================
+
+Developers who want a secure, fully decentralized and trustless method of
+verifying Bitcoin transactions for their Ethereum and smart contract applications.
+
+BTC Relay is a building block for developers that want interoperability between
+Ethereum and Bitcoin.  For example, developers who want to allow their users to
+pay with Bitcoin to use their Ethereum application.
+
+
 Why isn't verifyTx / relayTx working?
 =============================
 
 * Does your transaction have at least 6 Bitcoin confirmations?
 
 * Did you pass the correct parameters to
   `construct the Merkle proof <https://www.npmjs.com/package/bitcoin-proof>`_ correctly?
-  Viewing the page source of the `examples <https://github.com/ethereum/btcrelay/tree/master#examples>`_
+  Viewing the page source of some `examples <https://github.com/ethereum/btcrelay/tree/master#examples>`_
   might help.
 
-* Did you send at least the fee as indicated by `getFeeAmount <https://github.com/ethereum/btcrelay/tree/master#getfeeamountblockhash>`_?
+* Did you send at least the fee as indicated by `getFeeAmount() <https://github.com/ethereum/btcrelay/tree/master#getfeeamountblockhash>`_?
 
 
 What prevents fees from being too high?
 =============================
 
 If a fee for any block header is too high, anyone may
-`changeFeeRecipient <https://github.com/ethereum/btcrelay/tree/master#changefeerecipientblockhash-fee-recipient>`_
+`changeFeeRecipient() <https://github.com/ethereum/btcrelay/tree/master#changefeerecipientblockhash-fee-recipient>`_
 to themselves.
 
-They can compare the current fee against `getChangeRecipientFee <https://github.com/ethereum/btcrelay/tree/master#getchangerecipientfee>`_
-to see if the fee is excessive.  Callers of ``changeFeeRecipient``
+They can compare the current fee against `getChangeRecipientFee() <https://github.com/ethereum/btcrelay/tree/master#getchangerecipientfee>`_
+to see if the fee is excessive.  Callers of ``changeFeeRecipient()``
 must make sure to satisfy all `requirements <https://github.com/ethereum/btcrelay/tree/master#changefeerecipientblockhash-fee-recipient>`_
 for successful completion.
 

docs/status.rst

@@ -29,13 +29,13 @@ account that was first to successfully submit the block header to BTC Relay.
 What is the fee for previous blocks?
 =============================
 
-Use `getFeeAmount. <https://github.com/ethereum/btcrelay/tree/master#getfeeamountblockhash>`_
+Use `getFeeAmount(). <https://github.com/ethereum/btcrelay/tree/master#getfeeamountblockhash>`_
 
 
 What can I do if the fee is too high?
 =============================
 
-An option is to `changeFeeRecipient <https://github.com/ethereum/btcrelay/tree/master#changefeerecipientblockhash-fee-recipient>`_
+An option is to `changeFeeRecipient() <https://github.com/ethereum/btcrelay/tree/master#changefeerecipientblockhash-fee-recipient>`_
 to yourself.  Make sure you satisfy all requirements for successful completion.