wip

Author: 2color

docs/concepts/lifecycle.md

@@ -5,25 +5,26 @@ description: Learn about the lifecycle of data in IPFS.
 
 # The lifecycle of data in IPFS
 
-- [1. Content-addressable representation](#1-content-addressable-representation)
-- [2. Pinning](#2-pinning)
-- [3. Retrieval](#3-retrieval)
-- [4. Deleting](#4-deleting)
+- [1. Content-addressing](#1-content-addressing)
+- [2. Providing](#2-providing)
+- [3. Retrieving](#3-retrieving)
 - [Learn more](#learn-more)
 
-## 1. Content-addressable representation
+## 1. Content-addressing / Merkelizing
 
-The file is transformed into a content-addressable representation using a CID. The basic idea is that this representation makes files and directories **content-addressable** via CIDs by chunking files into smaller blocks, calculating their hashes, and constructing a [Merkle DAG](./merkle-dag.md).
+The first stage in the lifecycle of data in IPFS is to address it by CID. This is a local operation that takes arbitrary data and encodes it so it can be addressed by a CID.
 
-## 2. Pinning
+The exact process depends on the type of data. For files and directories, this is done by constructing a [UnixFS](./file-systems.md#unix-file-system-unixfs) [Merkle DAG](./merkle-dag.md). For other data types, such as dag-cbor, this is done by encoding the data with [dag-cbor](https://ipld.io/docs/codecs/known/dag-cbor/) which is hashed to produce a CID.
+
+## 2. Providing
 
 In this stage, the blocks of the CID are saved on an IPFS node (or pinning service) and made retrievable to the network. Simply saving the CID on the node does not mean the CID is retrievable, so pinning must be used. Pinning allows the node to advertise that it has the CID, and provide it to the network.
 
 - **Advertising:** In this step, a CID is made discoverable to the IPFS network by advertising a record linking the CID and the server's IP address to the [DHT](./dht.md). Advertising is a continuous process that repeats typically every 12 hours. The term **publishing** is also commonly used to refer to this step.
 
 - **Providing:** The content-addressable representation of the CID is persisted on one of web3.storage's IPFS nodes (servers running an IPFS node) and made publicly available to the IPFS network.
 
-## 3. Retrieval
+## 3. Retrieving
 
 In this stage, an IPFS node fetches the blocks of the CID and constructs the Merkle DAG. This usually involves several steps:
 
@@ -35,13 +36,13 @@ In this stage, an IPFS node fetches the blocks of the CID and constructs the Mer
 
 - **Local access:** Once all blocks are present, the Merkle DAG can be constructed, making the file or directory underlying the CID successfully replicated and accessible.
 
-## 4. Deleting
+<!-- ## 4. Deleting
 
 At this point, the blocks associated with a CID are deleted from a node. **Deletion is always a local operation**. If a CID has been replicated to other nodes, it will continue to be available on the IPFS network.
 
 :::callout
 Once the CID is replicated by another node, it is typically advertised to DHT by default, even if it isn't explicitly pinned.
-:::
+::: -->
 
 ## Learn more
 

docs/how-to/ipfs-in-web-apps.md

@@ -21,7 +21,7 @@ There are good reasons for this like security and resource management, but ultim
 
 As a developer, IPFS exposes three main operations for interacting with the network:
 
-- **Addressing data with CIDs** (also known as merkelising): taking arbitrary data and encoding so its addressable by CID. For example, given a file and encoding it so it can be addressed by a CID.
+- **Addressing data with CIDs** (also known as merklizing): taking arbitrary data and encoding so its addressable by CID. For example, given a file and encoding it so it can be addressed by a CID.
 - **Providing data by CID**: making data addressed by a CID retrievable by other peers, either by running a node or with a pinning service.
 - **Retrieving data by CID**: given a CID, IPFS finds providers (peers who share the block), connects to them, fetches the blocks, and verifies.