improving copy

content/index.md

@@ -7,7 +7,22 @@ stars = "multiformats/multiformats"
 
 Every choice in computing has a tradeoff. This includes formats, algorithms, encodings, and so on. And even with a great deal of planning, decisions may lead to breaking changes down the road, or to solutions which are no longer optimal. Allowing systems to evolve and grow is important.
 
-Multiformats is a collection of protocols which aim to future-proof systems, today. They do this mainly by enhancing format values with self-description. This allows interoperability, protocol agility, and helps us avoid lock in.
+- [What are Multiformats?](#what-are-multiformats)
+- [Multiformat protocols](#multiformat-protocols)
+- [Projects using Multiformats](#projects-using-multiformats)
+- [Contribute & Community](#contribute-community)
+
+## What are Multiformats?
+
+The Multiformats Project is a collection of protocols which aim to future-proof systems, today. They do this mainly by enhancing format values with self-description. This allows interoperability, protocol agility, and helps us avoid lock in.
+
+The self-describing aspects of the protocols have a few stipulations:
+
+- They MUST be _in-band_ (with the value); not _out-of-band_ (in context).
+- They MUST avoid _lock-in_ and promote _extensibility_.
+- They MUST be compact and have a _binary-packed_ representation.
+- They MUST have a _human-readable_ representation.
+
 
 ## Multiformat protocols
 
@@ -24,23 +39,20 @@ Currently, we have the following multiformat protocols:
 - [multikey](https://github.com/ipfs/specs/issues/58) <small>(WIP)</small> - self-describing <span class="mfc mfc-multikey">keys and proofs</span>
  -->
 
-Several of the multiformats have stable specs and stable implementations. We're are working on the others. We prioritize their usage as soon as possible, as what they offer -- protocol interoperability and future-proofing -- has real-world consequences today.
+Each of the projects has its list of implementations in various languages.
 
-Towards that end, we are encouraging improvements to WIP protocols, and implementations of all. Please contribute to the projects on Github.
+### Project Status
 
-The self-describing aspects of the protocols have a few stipulations:
+Several of the multiformats have stable specs and stable implementations. We're are working on the others. We prioritize their usage as soon as possible, as what they offer -- protocol interoperability and future-proofing -- has real-world consequences today.
 
-- They MUST be _in-band_ (with the value); not _out-of-band_ (in context).
-- They MUST avoid _lock-in_ and promote _extensibility_.
-- They MUST be compact and have a _binary-packed_ representation.
-- They MUST have a _human-readable_ representation.
+Towards that end, we are encouraging improvements to WIP protocols, and implementations of all. Please contribute to the projects on Github.
 
 
 ### A note on the word Multiformats
 
 Multiformats is the name for the organization, but it can also be used to refer to protocols; for instance, in the sentence "Use one of the multiformats". Formats is interchangeable with protocols, here. We try to capitalize Multiformats when it refers to the organization, on GitHub.
 
-### Projects using Multiformats
+## Projects using Multiformats
 
 The Multiformats project began through [the IPFS Project](https://ipfs.io). It is used extensively in projects like
 
@@ -59,13 +71,15 @@ The Multiformats project began through [the IPFS Project](https://ipfs.io). It i
 	</li>
 </ul>
 
-### Community
+## Contribute & Community
 
-<a href="/">The Multiformats Project</a> is an Open Source software project. It is built by a large community of contributors.
+<a href="/">The Multiformats Project</a> is an Open Source software project. It is built by a large community of contributors. Please join us on Github or IRC to request features, file bugs, contribute code, improve documentation, and ask questions. We have a very open and welcoming community.
 
 - [Github Project](https://github.com/multiformats/multiformats)
 - [Website Repository](https://github.com/multiformats/website)
 - IRC Channel: `#ipfs` on irc.freenode.org
+- [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md)
+- [Contributing Guide](https://github.com/multiformats/multiformats/blob/master/contributing.md)
 
 Multiformats was started and is sponsored by:
 

content/multihash.md

@@ -8,6 +8,19 @@ stars = "multiformats/multihash"
 
 Multihash is a protocol for differentiating outputs from various well-established hash functions, addressing size + encoding considerations. It is useful to write applications that future-proof their use of hashes, and allow multiple hash functions to coexist.
 
+<!-- manual toc unfortunately. dont want all qs printed here -->
+
+- [Safer, easier cryptographic hash function upgrades](#safer-easier-cryptographic-hash-function-upgrades)
+- [The Multihash Format](#the-multihash-format)
+- [Implementations](#implementations)
+- [Examples](#examples)
+- [F.A.Q.](#f-a-q)
+- [About](#about)
+  - [Specification](#specification)
+  - [Credits](#credits)
+  - [Open Source](#open-source)
+  - [Part of the Multiformats Project](#part-of-the-multiformats-project)
+
 ### Safer, easier cryptographic hash function upgrades
 
 Multihash is particularly important in systems which depend on [**cryptographically secure hash functions**](https://en.wikipedia.org/wiki/Cryptographic_hash_function). Attacks [may break](https://en.wikipedia.org/wiki/Hash_function_security_summary) the cryptographic properties of secure hash functions. These [_cryptographic breaks_](https://en.wikipedia.org/wiki/Cryptanalysis) are particularly painful in large tool ecosystems, where tools may have made assumptions about hash values, such as function and digest size. Upgrading becomes a nightmare, as all tools which make those assumptions would have to be upgraded to use the new hash function and new hash digest length. Tools may face serious interoperability problems or error-prone special casing.
@@ -174,6 +187,22 @@ The multihash examples are chosen to show different hash functions and different
 
 ## F.A.Q.
 
+> #### Q: Why have digest length as a separate number?
+
+Because combining hash function code and hash digest length ends up with a function code really meaning "function-and-digest-size-code". Makes using custom digest sizes annoying, and much less flexible. We would need hundreds of codes for all the combinations people would want to use.
+
+> #### Q: Why varints (variable integers)?
+
+So that we have no limitation on functions or lengths.
+
+> #### Q: What kind of varints?
+
+A Most Significant Bit unsigned varint, as defined by the [multiformats/unsigned-varint](https://github.com/multiformats/unsigned-varint) doc.
+
+> #### Q: Don't we have to agree on a table of functions?
+
+Yes, but we already have to agree on functions, so this is not hard. The table even leaves some room for custom function codes.
+
 > #### Q: Why not use `"sha256:<digest>"`?
 
 For three reasons:
@@ -204,7 +233,7 @@ Three options to add custom hash functions:
 
 > #### Q. I want to upgrade a large system to use Multihash. Could you help me figure out how?
 
-Sure, ask for help in IRC, github, or other fora. See the [Multiformats Community](../#community) listing.
+Sure, ask for help in IRC, github, or other fora. See the [Multiformats Community](../#contribute-community) listing.
 
 > #### Q. I wish Multihash would _______. I really hate _______.
 

layouts/_default/single.html

@@ -39,6 +39,7 @@
 
       <div class="row">
         <div class="push-2 col-8">
+
           {{ .Content }}
         </div>
       </div>

versions/history

@@ -1,3 +1,4 @@
 QmXzJcnFHXErv8iAd8W5vMYWp8bLBpvU1CFNpmGu2nKB3W
 QmdQmEzVEJ16eP5DpHwGf6WDCtKXC8DpwxnP4eosPFgDC9
 Qmf38duto7uZtQdP4svfSJnuU7oXs4hfwaC1KQQbjN99Cp
+QmU7EbHymE3LCbJPen3EzkQuYMPF89TLpbvhLRZqx5MqCx