ipfs-inactive/docs

Refactor/expand docs on ipfs.io

magik6k opened this issue · 9 comments

magik6k commented

Currently the https://ipfs.io/docs/ page only gives some basic guide on IPFS plus some
'random' info in examples. It's not easy to get more in-depth info on IPFS without digging
deeper into the github repos, something that requires more effort than many people new to
the project are willing to put into it.

While there are many valuable docs, what is missing is a good place for them to live.

We need something:

  • Convenient to browse
  • Containing information that is easy to understand, low noise
  • Containing enough information to understand how to:
    • Build a website on IPFS
    • Build an application using IPFS
    • Put 1TB+ of data in IPFS
    • Build API client library
    • Recreate considerable chunk of IPFS implementation
  • Within 4-5 clicks from documentation root

I found few documentation engines that may work:

MkDocs is really simple to get going and uses markdown which is familiar, though
it's seems to be very limited when compared to Sphinx. Using Sphinx would mean
that we'd have to port at least a considerable chunk of MD docs to reST (there
are tools to help with this) but it's probably a better choice for large docs.

What could be in there:

* Getting started
	* Overview
		* Content Addressing
			* DAG
		* Multiformats
			* Multihash
			* Multicodec
			* Multibase
		* CID
		* UnixFS / IPLD
	* Installation
		* go-ipfs
			* dists / sources
		* js-ipfs
			* npm / ??
	* Setup
		* Repo init
			* Profiles
		* Running daemon
			* Linux: systemd / init
			* OSX / Windows: like Linux
	* Basic usage:
		* CLI
			* Single file
				- Say where it lands / what happens, touch on the DHT
				- Get from gateway
			* Directory
				- Create some structure, 1-2 dirs, 2-3 files
				- View with ls/cat
					- ls by hash/path, hash of path
			* IPNS / ipfs name
				* Publish some file/directory
				* Resolve with `name resolve`
				* Resolve on gateway
		* Web-UI
			* Say it exists..
* HTTP/CLI API
	- Mention that http used by CLI when daemon is running
	- Autogenerated structure like https://ipfs.io/docs/api/, but with some more structure..
	- Possibly a way to add some more docs to cammands
* JS API
	- Possibly generated
* IPFS Stack
	* Big fancy graph/image
	* Multiformats in detail
		* Multihash
		* Multicodec
		* Multibase
		* Multiaddr
	* IPLD/CID concepts
		* IPLD Paths
		* IPLD Resolvers
		* IPLD ???
	* Libp2p
		* Transports
		* Streams
		* Swarm
			* PeerIDs
			* Bootstrap
		* DHT
		* ???
	* Bitswap
* Using IPFS
	* Websites
		* IPNS
		* DNSLINK
	* Archives
		* Handling large data volumes
		* CRDTs?
	* Data Delivery
		* Large data valumes, optimizations
		* Deduplication
	* Some fuse use-case
* go-side
	* Config
	* Plugins
* js-side
	* Config
	* In-Browser use
	* API

Roadmap:

  • Decide if it's the right way forward, which engine to use
  • Setup the repo
  • Get some initial docs structure going (have Getting started section done)
  • Start deploying it on ipfs.io
  • Expand to the point where it documents most of the stack

Notes:

It will be a lot of work to do this well, good news is that a big chunk of this
is already wirtten, so bulk of the work would be to get the information linked
together in one place.

To keep things form becoming outdated we should have some way to track the docs,
One way of doing this would be to put a footer in each file saying last reviewed 01/01/2018,
then have some tool to tell which docs may need rewieving.

This issue is mostly to bring back some life to the documentation, I'd like to get some comments
on this before doing anything more in this direction.

Deleted user commented

cc @kyledrake

We want to work on it this quarter. Ideally the result would:

  • be a simple docs.ipfs.io portal as the entrypoint to all documentation
  • automatically build and deploy to IPFS
  • automatically build api reference docs for go and js package, and mount them into docs.ipfs.io (e.g. docs.ipfs.io/go-ipfs-api)
  • fulltext search over content and api docs
  • then: start working on the content structure, and write more content
  • impose api docs coverage checks on all packages

Once there's decent tooling in place, the barrier to working on docs will be much lower, and people will be encouraged to write docs because the way to results is much shorter :)

Deleted user commented

cc @magik6k

State of The Docs, 6-Nov-2017

  • http://docsdev.ipfs.team (ipfs/docs repo) is now a very basic Hugo site that we can use to start iterating. The reason we went with Hugo is simply that all our other websites use the same tool, and that don't know enough about our problems yet to pick a more complex tool.
  • The master branch of ipfs/docs is automatically deployed to http://docsdev.ipfs.team

Let's start adding content!

(I believe @kyledrake has some unfinished hugo/html business to push to master)

  • 🎉2
Deleted user commented

Whoops -- it's http://docsdev.ipfs.team. Fixing the typo above too.

Deleted user commented

A few notes about docsdev.ipfs.team:

  • There's a very simple client-side search using lunr.js. We aim to replace this with an IPLD-based search.
  • The design is only rudimentary, expect it to look more like ipfs.io soon.
  • A few things are broken :)
dignifiedquire commented

Just a note and you might know this, but it is verrrry slow to load (8 seconds for the full page without cache)

magik6k commented

I'll try to get some rough structure going soon so people can jump onto here.

kyledrake commented

Just pushed it. Go nuts!

magik6k commented

Added some structure in #41

Mr0grog commented

I’m closing this since we now have a rethought, shipped, working information architecture and site as of #68 and #80. There’s certainly room for improvements to the design or to the underlying static site framework (see #71), but I think those can now be handled in more specific issues with a smaller scope.

Feel free to comment if we should re-open it!