Refactor/expand docs on ipfs.io

[magik6k]

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:

• http://www.sphinx-doc.org/en/stable/index.html

  • Pros
    • Static output, works on ipfs
    • Used for large docs
      • https://docs.python.org/3/ is one example
      • Few others: http://www.sphinx-doc.org/en/stable/examples.html
    • Supports Internationalization
    • Very powerful
  • Cons
    • Uses custom markup - reStructuredText markup - http://www.sphinx-doc.org/en/stable/rest.html
      • Can support markdown: http://www.sphinx-doc.org/en/stable/markdown.html
      • Introduces a bit of a 'learning curve', though it isn't that bad

• https://readthedocs.org/

  • Based on Sphinx
  • Pros
    • Looks nice out of the box
    • Probably less setup
  • Cons
    • Non-static, hosted
    • See Sphinx

• http://www.mkdocs.org/

  • Pros
    • Simple to setup
    • Static output, works on ipfs
    • Uses markdown by default
  • Cons
    • Doesn't support multi-level structure well
    • Might be hard to scale to larger docs
    • Not nearly as powerful as Sphinx

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.

[ghost]

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 :)

[ghost]

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)

[ghost]

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

[ghost]

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]

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

[magik6k]

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

[kyledrake]

Just pushed it. Go nuts!

[magik6k]

Added some structure in https://github.com/ipfs/docs/pull/41

[Mr0grog]

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!