Gather & organize links to existing docs and examples
Mr0grog opened this issue · 4 comments
We have a fair amount of documentation and examples scattered across various GitHub repos where people are often failing to find it (e.g. #13, ipfs/js-ipfs/examples, anything with checkmarks in the “has /docs” or “has /examples” columns in the repo spreadsheet)
Before we worry about writing new docs, improving other docs, and so on, we should inventory and link to all that we already have from the new docs site.
A quick survey of what we’ve got out there, not covering things that live in shipyard:
Current docs site
- Installation Guide https://ipfs.io/docs/install/ or https://github.com/ipfs/website/blob/master/content/docs/install.md
- Getting Started Guide https://ipfs.io/docs/getting-started/ or https://github.com/ipfs/website/blob/master/content/docs/getting-started.md
- HTTP API https://ipfs.io/docs/api/ or https://github.com/ipfs/website/blob/master/content/docs/api.md
- Generated via https://github.com/ipfs/http-api-docs, but out of date/non-functional
- Overlaps heavily with https://github.com/ipfs/interface-ipfs-core, which is much better for the commands it does cover (but it doesn’t explain how those translate to HTTP Requests/Responses)
- CLI Commands https://ipfs.io/docs/commands/ or https://github.com/ipfs/website/blob/master/content/docs/commands.md
- Appears to be generated, but not sure by what (possibly: https://github.com/ipfs/go-ipfs/blob/master/bin/gencmdref)
- Examples in https://github.com/ipfs/website/tree/master/static/docs/examples
- Note the stuff in https://github.com/ipfs/website/tree/master/content/docs/examples is just a table of contents and a webapp that loads and renders the markdown of the actual docs
- These are often a bit thin or not super up-to-date
Interface “specs” at https://github.com/ipfs/interface-ipfs-core
- The best reference for the available commands, but focus specifically on the JS API, don’t describe the Go functions at all, and don’t explain how to do the commands as HTTP Requests
Main IPFS Repo
- Quick Overview
- Project/Repo Directory
- Whitepaper https://github.com/ipfs/ipfs/blob/master/papers/ipfs-cap2pfs/ipfs-p2p-file-system.pdf
- Roadmap https://github.com/ipfs/ipfs/blob/master/ROADMAP-TO-1.0.0.md
- Implementation Status https://github.com/ipfs/ipfs/blob/master/IMPLEMENTATION_STATUS.md
Specs
- https://github.com/ipfs/specs
- TODO: better account of actual status of each of these
JS IPFS
- Has quite a few examples and tutorials: https://github.com/ipfs/js-ipfs/tree/master/examples
- Not sure if we really want to duplicate the table of contents/readme
- Project README has API docs and a fair amount of other useful bits
Go IPFS https://github.com/ipfs/go-ipfs/tree/master/docs
- Has quite a few docs at: https://github.com/ipfs/go-ipfs/tree/master/docs
- All singular markdown docs, so we could probably pull them into the docs site pretty easily
interface-ipfs-core https://github.com/ipfs/interface-ipfs-core
- Generally the best detailed reference for commands and what they do, but very JS focused (not Go, HTTP, or CLI)
Archives
- Replicating Large Datasets https://github.com/ipfs/archives/tree/master/tutorials/replicating-large-datasets
IPFS Cluster
- Quickstart is in the README https://github.com/ipfs/ipfs-cluster
- Usage Guide/Manual https://github.com/ipfs/ipfs-cluster/blob/master/docs/ipfs-cluster-guide.md
- Building a cluster https://github.com/ipfs/ipfs-cluster/blob/master/docs/HOWTO_build_and_update_a_cluster.md
- Architecture https://github.com/ipfs/ipfs-cluster/blob/master/architecture.md
- Generatable reference docs https://godoc.org/github.com/ipfs/ipfs-cluster
- In-progress use-case docs:
Other projects:
- ipfs-service-worker
- Has an example https://github.com/ipfs/ipfs-service-worker/tree/master/examples/use-from-another-page
- But not much descriptive anything to help explain it
- ipfs-pack https://github.com/ipfs/ipfs-pack
- README is the only docs
- There is a PR for a tutorial; not sure if up-to-date ipfs-shipyard/ipfs-pack#8
Discourse (FAQ category in particular)
- “Old” FAQ: https://discuss.ipfs.io/c/help/Old-FAQ
Awesome IPFS https://github.com/ipfs/awesome-ipfs lists lots of IPFS-based projects
NOTE:
- Most of the
go-*repos generate reference docs, but they rarely contain much useful descriptive info. e.g. https://godoc.org/github.com/ipfs/go-ipfs-api (common) vs. https://godoc.org/github.com/ipfs/go-ipfs/filestore (unusually detailed) - Most of the
js-*repos do not generate reference docs (but they tend to have decent hand-written docs in their READMEs).
Hello, I'm consolidating ipfs-cluster documentation in cluster.ipfs.io. That means, all the READMEs will point to it and it will be removed from the cluster repository.
Good to know. It seems like the goal is to give Cluster an entirely separate site with all the related resources, so the new IPFS docs should just point to it instead of hosting any guides or docs about it. Does that seem right?
Correct