Create concept doc for pinning (for #94) #105
Conversation
There was a problem hiding this comment.
Thanks, @rjharmon, this feels like a really great start. I’m sorry it took me several days to review it :\
I’ve added some comments inline — mostly small stuff except the pinning services section at the end.
Also, could you please rewrite this commit to include a license and signoff line as described in our contributor guide? Thanks!
content/guides/concepts/pinning.md
Outdated
| parent: concepts | ||
| --- | ||
|
|
||
| ## Summary |
There was a problem hiding this comment.
Would you please remove this heading? We can just treat the first section of all docs as the introduction and summary. There are a couple reasons for this:
-
I think this subhead isn’t informing the reader about much and is mostly visual noise.
-
It should be possible for us to easily generate a nice summary of each concept for the listing page https://docs.ipfs.io/guides/concepts/ (yes that page certainly still needs work). When you have this heading here, it gets in the way of that:
content/guides/concepts/pinning.md
Outdated
|
|
||
| ## Context | ||
|
|
||
| An IPFS node can store data based on different kinds of user events. For instance, a person may add a file with `ipfs add ...`. Or a piece of unknown IPFS content can be requested, and the node can consult with its peers to find this data - the result will be stored in the local cache. These data can use different policies for managing the cache - `ipfs add ...` will automatically pin the content. Other IPFS commands do not include automatic pinning. |
There was a problem hiding this comment.
For instance, a person may add a file with
ipfs add ....
We started this doc as something addressed to the reader in the second person as “you.” I think it would be good to carry that through here (we aren’t talking about how people throughout the world are using IPFS; we talking about you managing your node), so it would be better to say “for instance, you may add…”
Or a piece of unknown IPFS content can be requested
I think it would be good to provide an example of how this happens that feels more concrete. Maybe something like:
“Or your node can store data you request it from other peers, such as when you load a web page through the gateway at http://localhost:8080/ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco or run a command like ipfs cat ....”
These data can use different policies for managing the cache
I’m not sure this is the best way to frame it — there’s no policy for different kinds of data; only for different ways of adding the data to your node. I think you could just cut this part of the sentence and it would be a little clearer and more accurate.
content/guides/concepts/pinning.md
Outdated
|
|
||
| An IPFS node can store data based on different kinds of user events. For instance, a person may add a file with `ipfs add ...`. Or a piece of unknown IPFS content can be requested, and the node can consult with its peers to find this data - the result will be stored in the local cache. These data can use different policies for managing the cache - `ipfs add ...` will automatically pin the content. Other IPFS commands do not include automatic pinning. | ||
|
|
||
| When garbage-collection is triggered on a node, any pinned content is automatically exempt from deletion. Non-pinned data is otherwise eligible to be deleted to save space (if requested, this data can be re-retrieved from another node. |
There was a problem hiding this comment.
“Garbage collection” should not be hyphenated.
is otherwise eligible to be deleted
I think this could be simplified and made easier to read by just saying “may be deleted”.
Also, the closing parenthesis at the end is missing.
content/guides/concepts/pinning.md
Outdated
|
|
||
| ## Pinning Services | ||
|
|
||
| If you don't want to run your own IPFS node, you can use a pinning service. Such a service normally trades money for the service of guaranteeing they'll keep your data pinned. |
There was a problem hiding this comment.
If you don't want to run your own IPFS node
I feel like this is a little off. You should still be running IPFS for lots of other reasons, even if you aren’t pinning much data locally. Some better example cases here might be:
- You don’t have a lot of disk space, but you want to ensure some data sticks around
- Your computer is a laptop or phone or a tablet that will have intermittent connectivity to the network, but you want to be able to access your file on IPFS from anywhere at any time, even when the device you added it from is offline.
- You want a backup that ensures your data is always available from another computer on the network in case you accidentally delete or garbage-collect on your own computer.
License: MIT Signed-off-by: Randall Harmon <rjharmon0316@gmail.com>
|
@Mr0grog - Okay, I pushed a replacement on my Needs review. |
License: MIT Signed-off-by: Rob Brackett <rob@robbrackett.com>
|
Looks great; thanks so much for this, @rjharmon! |
No description provided.