Data-not-files: IPFS 101, FAQ, & Hashing changes

[Annamarie2019]

Changes 3 files to address this issue (Answers issue #996):

• IPFS 101 (How it works): The ideal place for the answer to 'Why doesn't my SHA hash match my CID' is in the introductory, high-level doc, as it addresses a naive question.
• FAQ: I don't like repeating in doc, but I believe FAQs are the one exception: They should actually be a restatement--said in a concise way--to deflect constant questions to the team.
• Hashing: The bottom section was kind of the start of the whole thing. The answer isn't really gotten to until the bottom (like a mystery novel, inductive reasoning). I suggest using deductive reasoning (state the thesis first) in technical writing. Also, It seems to me that we're explaining precisely, step-by-step, how NOT to do something, which is kind of weird (Open the door to the oven while the cake is baking; Darn, that won't work! Oops, the cake collapsed, too late.) If I had it my way, I would not get in that business, but Volker and Johnny seem to value it (and, as engineers, they represent our audience), so I moved the heart of the answer up top ( the "this won't work" part....made it deductive), a little word-smithing, and clarified the heading, so they know what they're getting into.

After examining the overall Info Architecture of the IPFS doc, I think this repetition is fine: High level for newbies, occasional FAQs to reduce user frustration and save our time, and a detailed explanation for our nerdy friends.

[vmx]

I've left a few comments, the rest looks great!

[johnnymatthews]

This is a great PR! Everything is very clear and easy to understand! Nice work! Just requested a few minor changes.

[johnnymatthews]

Suggested change

	## Example: Content Identifiers are not file hashes
	## Content identifiers are not file hashes

[johnnymatthews]

content address

Is this meant to be content's address or content identifier?

[Annamarie2019]

Content identifier is more accurate in this context. Just committed to the nodes branch.

[filecorgi]

• Image optimization came back clean!
• Vuepress build was successful!

docs/concepts/faq.md:

• The phrase ‘a lot of’ might be wordy. Consider using “many”, “numerous” or “countless”.

  ...I start contributing to IPFS? There are a lot of ways you can contribute to ...
                                             ^^^^^^^^
  

• This phrase is redundant. Consider writing “evolve”.

  ...amless as possible, but we expect it to evolve over time. You can view the d...
                                             ^^^^^^^^^^^^^^^^
  

• Consider using “many”.

  ...sand contributors around the world from many different projects. There are a...
                                             ^^^^^^^^^^^^^^
  

• Possible typo detected.

  ...ment on many related protocols, such as libp2p and Filecoin, with the aim of...
                                             ^^^^^^
  

docs/concepts/hashing.md:

• The adjective ‘full’ can be overused, consider replacing it with a synonym.

  ...given input. Have a look at Wikipedia's full list of hash functions  (opens ...
                                             ^^^^
  

• ‘exact same’ might be wordy. Consider a shorter alternative.

  ...e represented by SHA-1 as: However, the exact same input generates the follo...
                                             ^^^^^^^^^^
  

• You can shorten this phrase to avoid wordiness.

  ...2, base16, base32, etc.). In fact, IPFS makes use of that as part of its con...
                                             ^^^^^^^^^^^^
  

• As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.

  ...ptographic hashes come with a couple of very important characteristics: dete...
                                             ^^^^^^^^^^^^^^
  

• ‘exactly the same’ might be wordy. Consider a shorter alternative.

  ...- the same input message always returns exactly the same output hash uncorre...
                                             ^^^^^^^^^^^^^^^^
  

• Consider using a different adverb to strengthen your wording.

  ...l change in the message should generate a completely different hash unique -...
                                             ^^^^^^^^^^^^
  

• You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.

  ...ID equals the checksum for the file: As we can see, the hash included in the...
                                             ^^^^^^^^^^
  

• You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.

  ...le ubuntu-20.04.1-desktop-amd64.iso. As we can see, the hash included in the...
                                             ^^^^^^^^^^
  

docs/concepts/how-ipfs-works.md:

• Only proper nouns start with an uppercase character (there are exceptions for headlines).

  ...e identification via content addressing Content linking via directed acyclic...
                                             ^^^^^^^
  

• The phrase ‘look for a book’ is used very frequently. Consider using a less frequent alternative to set your writing apart from others.

  ... do all the time. For example, when you look for a book in the library, you ...
                                             ^^^^^^^^^^^^^^^
  

• For conciseness, consider replacing this expression with an adverb.

  ... for the internet and on your computer! Right now, content is found by locat...
                                             ^^^^^^^^^
  

• Do not use a colon (:) before a series that is introduced by a preposition (‘as’). Remove the colon or add a noun or a noun phrase after the preposition.

  ...now, content is found by location, such as: https://en.wikipedia.org/wiki/Aa...
                                             ^^^
  

• You can shorten this phrase to avoid wordiness.

  ... introduction. Many distributed systems make use of content addressing throu...
                                             ^^^^^^^^^^^
  

• Possible missing comma found.

  ...hes as a means for not just identifying content but also linking it together...
                                             ^^^^^^^
  

• Possible missing comma found.

  ...PLD translates between hash-linked data structures allowing for the unificat...
                                             ^^^^^^^^^^
  

• Consider using “many”.

  ..., but you can structure a Merkle DAG in many different ways. For example, Gi...
                                             ^^^^^^^^^^^^^^
  

• This phrase is redundant. Consider using “inside”.

  ...DAG that has many versions of your repo inside of it. To build a Merkle DAG ...
                                             ^^^^^^^^^
  

• It seems likely that a singular genitive (’s) apostrophe is missing.

  ...ew window). Merkle DAGs are a bit of a "turtles all the way down"  (opens ne...
                                             ^^^^^^^
  

• You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.

  ...G, i.e., parts of different Merkle DAGs can reference the same subset of dat...
                                             ^^^^^^^^^^^^^
  

• You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.

  .... Your old version and your new version can refer to the same blocks for eve...
                                             ^^^^^^^^^
  

• You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.

  ...e same blocks for everything else. This can make transferring versions of la...
                                             ^^^^^^^^
  

• Possible missing comma found.

  ...transfer the parts that are new or have changed instead of creating entirely...
                                             ^^^^^^^
  

• Possible typo detected.

  ... find content, you ask these peers. The libp2p project  (opens new window) i...
                                             ^^^^^^
  

• Possible typo detected.

  ...o each other. (Note that, as with IPLD, libp2p can also be used as a tool fo...
                                             ^^^^^^
  

• Consider a shorter alternative to avoid wordiness.

  ... location of those peers (routing). So, in order to get to content, you use ...
                                             ^^^^^^^^^^^
  

• Possible typo detected.

  ...So, in order to get to content, you use libp2p to query the DHT twice. You'v...
                                             ^^^^^^
  

• ‘under discussion’ might be wordy. Consider a shorter alternative.

  ...are other content replication protocols under discussion  (opens new window)...
                                             ^^^^^^^^^^^^^^^^
  

• ‘under discussion’ might be wordy. Consider a shorter alternative.

  ...ns new window). There's also a proposal under discussion to extend the Bitsw...
                                             ^^^^^^^^^^^^^^^^
  

• Possible typo detected.

  ...e Content Identifiers are not hashes. # Libp2p What makes libp2p especially ...
                                             ^^^^^^
  

• Possible typo detected.

  ...ers are not hashes. # Libp2p What makes libp2p especially useful for peer-to...
                                             ^^^^^^
  

• Reduce redundancy by only using “bit”.

  ...to talk to each other about, you send a little bit of each thing, and the ot...
                                             ^^^^^^^^^^
  

• Possible typo detected.

  ... content using a DHT that's provided by libp2p, open a connection to any pro...
                                             ^^^^^^
  

[johnnymatthews]

I'm getting confused with so many PRs working on the same files. @Annamarie2019 can we close this PR or are you planning on getting it merged along with other PRs?

[Annamarie2019]

Sorry, that should have gone to the data-not-files branch. I'll close this one.