In all the places where we say "for help, go to discourse", make it link to the "help" category rather than the main page.

Also write a nice orientation in about the help category (currently it's the default starter text)

Expect an update on the Q4/2017 work and the plans for Q1+Q2/2018 soon.

We should rework the current example and add other examples to libp2p.

Not sure where to place this, so putting it here in the meantime.

Deploying your application and adding https

We have a dokku setup for deploying applications. To deploy do (you have to have permission first):

# if you already have added the remote, you don't need to do it again
> git remote add dokku [email protected]:webrtc-star-signalling
> git push dokku master

You can replace webrtc-star-signalling with whatever your applications name is. Once you push it, it'll start deploying and end with outputting the URL where it's deployed.

Adding custom domain + https

If you want to add https, you'll need to do two steps (using webrtc-star-signalling as a example). These commands needs to be run on the dokku host (currently cloud.ipfs.team)

> dokku domains:add star-signal star-signal.cloud.ipfs.team wrtc-star.discovery.libp2p.io

• star-signal is the application name
• star-signal.cloud.ipfs.team is the domain it's automatically deployed on when doing git push
• wrtc-star.discovery.libp2p.io is our custom domain that we've pointed to 188.166.203.82 already (usually done via DNSimple)

Now we can get a certificate.

> dokku letsencrypt star-signal star-signal.cloud.ipfs.team wrtc-star.discovery.libp2p.io

Same structure, just change domains:add for letsencrypt basically. Once this step is done, it should output done and you should be able to access both star-signal.cloud.ipfs.team and wrtc-star.discovery.libp2p.io over https.

I thought I'd help out by giving a few links to other open source projects with great documentation that I have come across. Learning from good examples would be a good start. This list is by no means exhaustive so please add more...

Python
what to like:

• simple
• good use of white space
• consistent style and format throughout
• can flip between versions
  built with: Sphinx

Pandas
what to like:

• excellent examples
• whole section displayed in one page instead of multiple pages
• table of contents stays open (but doesn't track with the scroll bar which is a pain)
• can flip between versions
  built with: Sphinx

scikit-learn
what to like:

• lots of description for each section with examples, great for learning
• provides reference material in each section
• a flowchart to help guide
  starters
• can flip between versions
  built with: Sphinx

Django
what to like:

• starts with a tutorial
• consistent style
• provides a how-to-guide
• simple color pallette
• can flip between versions
  built with: Sphinx

Trac
what to like:

• table of contents stays the same on every page so you can navigate around quickly
• very simple layout
• uses color in line with branding
  built with: Trac Wiki

Ceph
what to like:

• use of a colour scheme that relates to the logo/branding
• mostly about setting it up getting it working quickly, separates details out to another section
• separate architecture section
  built with: Sphinx, reST

Angular
what to like:

• separated table of contents uses drop-downs to give users flexible navigation
• has a cheat sheet
  built with: not sure, couldn't find it in the docs!

Others:
MongoDB
git
Chef
Ansible
D3

Further possible actions to take:

• Decide on a color scheme, how will it differ between projects/repo/components but still retain the IPFS brand
• Decide on a schema, or a "separation of concerns" for documentation. how do we separate out each area of communication for different users whilst maintaining consistency across the repos
• Decide on which set of tools to use, Sphinx, wiki, reST etc...

Currently, at https://ipfs.io/docs/install/ the install instruction on Mac OS X and Linux suggests to run the following command after downloading.

tar xvfz go-ipfs.tar.gz
./go-ipfs/install.sh

This fails because install.sh script is programmed to move ipfs directory of the current directory into the binpath. That ipfs directory is not in the current working directory yet. To fix this, either the install script can be updated to locate ipfs directory from within its current directory, not the current working directory or the instructions can be changed as following:

tar xvfz go-ipfs.tar.gz
cd go-ipfs
./install.sh

That said, the documentation at https://github.com/ipfs/docs/blob/master/content/start/install.md is correct as it does not use the install script.

I don't how where is the source of the deployed site, but instruction on https://ipfs.io/docs/install/ needs to be updated.

/CC @diasdavid

go-libp2p interfaces split over multiple packages, these could be moved into the root package

• transfer-files ipfs/js-ipfs#791
• file-feed ipfs/js-ipfs#716 will require orbit to be updated to new js-ipfs, which will only happen after the release

Let's use this issue as a place to gather observations & feedback from newbies.

This is related to #16

explicit descriptions of go-ipfs and js-ipfs on ipfs.io/docs and their status of interop etc

Goal: Help developers understand the status of concepts/technologies/approaches in IPFS. Let them know which things they should be using, what's happening, what's moving forward, what's a placholder for future work, etc. -- less emphasis on "is it done yet?", more emphasis on what you should use in which ways going forward.

The most consistent (and insistent) issue I heard from folks developing or attempting to develop software on top of IPFS was that they often can’t figure the status of various ideas, technologies, or approaches used (or going to be used) within the IPFS ecosystem. They are worried they shouldn’t be building on top of a particular API or protocol because it’s getting replaced or that they should be using it in a particular way (which way, they don't know) in order to best prepare for upcoming changes. Should they just build now and not worry about it, or hold off for something that's coming soon?

It's worth noting that they all said this at the same time as saying that better API documentation would be nice, but they've managed to figure a lot out by reading source code and puzzling around things. But understanding the direction of various parts of IPFS is something much more important that they can’t figure out that way.

Getting a handle on implementation status (as discussed in #35) is only a small part of this issue. The questions here are more like:

• What’s the deal and status with IPNS being slow? Should I even use it now? I know there’s some discussion about re-implementing it on top of libp2p pubsub — when is that happening? (IS that really happening?) How should I make use of things differently (or not) so my code functions optimally in future where that's how IPNS works?

• What's the deal with IPNS vs. IPRS? Is the spec final or still subject to change? The IPRS spec was written a year ago, but it doesn’t seem like things are using it? Is it still a thing or is it left behind? When will it be a concrete thing?

• What’s the deal with IPLD? Is it being used for the all (or any and which?) of the commands in go-ipfs or js-ipfs? If no, when? What’s solid about it and what’s not, and when (specifically or even just roughly) do we think it will be all solid? Should I be using it today?

• Similar questions for CIDs, for files vs. objects vs. dag, pretty much everything in ipfs/specs and ipld/specs. (Less so for libp2p/specs, which folks have said seems largely more stable and clear, and multiformats/specs, which, even though that repo is really uninformative, Multiformats’ other constituent are quite clear.)

• Hypothetical confused developer: "I'm so confused about these things that I don't know which one I should be using. Which ones do the maintainers really want me to use? Which ones do the maintainers specifically discourage using? Which things should I watch for in the coming months, etc"

Some Approaches

So what are the right approaches to solving this issue and how do we manage that work?

• A clear and updated Roadmap that focuses on these sorts of technology/usage issues rather than implementation, like the Roadmap to 1.0.0 does.

• Clear indicators in every spec and major repo (maybe on each major API section?) that accurately cover the current, up-to-date status. Many have no status indicators, others feel inaccurate — it might say something is a solid draft, but in reality, there are big discussions in the issues for it that indicate it’s not so solid at all, e.g. IPLD. These should be updated if major discussion on revising the spec begins somwhere (and, ideally, point to that discussion).

• What else?

We need to do some honest research to create a cohesive picture of things like:

• What are the general problems people are running into trying to use IPFS?
• What concepts are confusing, problematic, or just poorly understood and communicated?
• What are people trying to do with IPFS and how?

…which should give us a clearer, more concrete picture of what problems we need to solve.

Similar to #54, we need clear indicators of repos that aren’t software. See the “key” tab the repo inventory for some categorizations: https://docs.google.com/spreadsheets/d/1IDVAGfniyHCJLIxLc3y7K7YTOFGCtgwTVCZEojtNLlw/edit#gid=1355406849

I think I might categorize them this way:

• Discussion (repos focused on discussion in the issues or documenting/discussing notes and ongoing work, e.g. ipfs/research or ipfs/pm)
• Docs (repos focused on documentation, specs, etc.)
• Resource (Images, style guides, other common files/resources that aren’t software source code)

And I might mark the repos them this way:

• Description always starts with “<CATEGORY>:” e.g. “DISCUSSION: Repo to organize our ideas about research implementations of CRDTs.”
• Readme title always starts with “<Category>:” e.g. “Discussion: CRDT Research”
• Make sure the readme clearly describes how the repo should be used (e.g. content is in the issues, what kind of discussions belong here vs. discuss.ipfs.io)

UPDATE: Current Resolution

Repo categories:

• Documentation (📚)
• Discussion (💬)
• Infrastructure (🚚)
• Website (🤖)
• Resource (🎨)

Labeling:

• Add the topic type-<category> (e.g. type-discussion) (EDIT: was previously type:<category>)
• Prefix the README title with the category, e.g. Discussion: CRDT Research
• Prefix the repo description with the emoji associated with the category, e.g. “💬 Repo to organize our ideas about research implementations of CRDTs”
• Ensure the text immediately following the README title describes how the repo is used (e.g. it’s not a software project; it’s a place for discussion [in the issues] and to store links/papers/primers on related subject matter).

Repos That Need Fixing

The following is based on https://docs.google.com/spreadsheets/d/1IDVAGfniyHCJLIxLc3y7K7YTOFGCtgwTVCZEojtNLlw

Documentation:

• https://github.com/ipfs/ipfs
• https://github.com/ipfs/specs
• https://github.com/ipfs/papers
• https://github.com/ipfs/awesome-ipfs issue: ipfs/awesome-ipfs#158
• https://github.com/ipfs/glossary
• https://github.com/ipfs/reading-list
• https://github.com/ipfs/pdd

Website:

• https://github.com/ipfs/website
• https://github.com/ipfs/blog
• https://github.com/ipfs/distributions
• https://github.com/ipfs/archives
• https://github.com/ipfs/docs
• https://github.com/ipfs/cid-utils-website

Discussion:

• https://github.com/ipfs/community
• https://github.com/ipfs/pm
• https://github.com/ipfs/notes
• https://github.com/ipfs/research-blockchain-data
• https://github.com/ipfs/archive-format
• https://github.com/ipfs/bitswap-ml
• https://github.com/ipfs/apps
• https://github.com/ipfs/ops-requests (Or maybe this is infrastructure?)
• https://github.com/ipfs/2016-Q3-Workshop
• https://github.com/ipfs/in-web-browsers
• https://github.com/ipfs/test-lab
• https://github.com/ipfs/research-bitswap
• https://github.com/ipfs/research-CRDT
• https://github.com/ipfs/research-p2p-video
• https://github.com/ipfs/research
• https://github.com/ipfs/dynamic-data-and-capabilities

Infrastructure:

• https://github.com/ipfs/infrastructure
• https://github.com/ipfs/pinbot-irc
• https://github.com/ipfs/sprint-helper
• https://github.com/ipfs/jenkins-libs
• https://github.com/ipfs/websiter
• https://github.com/ipfs/jenkins
• ✘ https://github.com/ipfs/dweblink-infra (Deprecated)
• https://github.com/ipfs/ci-helpers
• https://github.com/ipfs/ci-sync

Resource:

• https://github.com/ipfs/logo
• https://github.com/ipfs/artwork

Let’s develop a roadmap towards a new, improved docs site in this repo. Here’s my take to get us started:

Overall, I think there are a few major problems users and contributors are running into that the new docs need to solve. First here’s a breakdown of the typical introductor experience:

1. For most all people, their journey with IPFS starts with blog post, Hacker News, or Reddit.
2. The only official resource we have that comprehensively describes IPFS is the white paper and that’s where most people wind up next when they decide to try and actually learn about or use IPFS.
   • Many folks skip or quickly skim this — its academic style can be intimidating and it assumes familiarity with a number of computer science or math concepts like graphs (as models of objects and relationships, rather than visualizations of 2/3/4-dimensional data)
   • More enterprising folks or those with a more expertise read it, but it’s very broad and very old. It doesn’t connect especially well with the concrete reality of IPFS today.
   • In both cases, people wind up making a number of assumptions that are inaccurate in different ways.
3. Go through the getting started tutorial
   • It doesn’t attempt to cover what is conceptually going on much at all, so any poor assumptions people have made from step 2 generally stay in place.
   • It is focused on the CLI, which is off-putting to many folks with less expertise and leaves a lot of developers who are immediately wondering how to interface with it programmatically in the cold.
   • It doesn’t leave you with any suggestions for next steps or what to do.
4. ???? At this point, we see a wide variety of things:
   • Giving up because it’s not clear
   • Try storing or sharing some files with a friend, which might work, but often leads to oddball questions about the basics on discuss.ipfs.io, IRC, or GitHub, because of conceptual assumptions they’ve made in steps 2 and 3. Some examples are questions about “uploading” (people with less expert programming background) or questions about why an IPFS hash doesn’t match a simple SHA-256 (or even a multihash) of the file they added to IPFS (more expert).
   • Spend a lot of time digging through GitHub trying to figure out how best to program against it as a library (especially if their primary language is not JS or Go). There is little about using IPFS programmatically on the docs site. We have a lot of docs that people never find because:
     • They’re buried in a source code repo.
     • They’re not even in the repo they’d expect. The docs in ipfs/interface-ipfs-core are dramatically better than the Rest API Docs, for example. One person said knowing those were there would have made things way easier, but they’d never seen them because they are only well linked from js-ipfs and this person wasn’t writing JavaScript (or Go).
     • There might be useful generated API docs, but we often don’t link them. (e.g. go-ipfs)

See lots more of this stuff over at #52 or https://gateway.ipfs.io/ipns/ipfs-docs-research.robbrackett.com/html/General-Notes.html .

What are the big learning/documentation problems here?

• No clear introduction to the overall idea of exactly how IPFS works and what it’s doing
• Lots of new concepts (whether you are knowledgeable about things like graphs or not) that are just very different from the web technologies people know today.
• Docs are inconsistently located and spread across a number of repos people have to hunt through.
• Clear, standard API docs are not always available.
• Hunting through GitHub is hard. (Which repos have docs? Where in the repo are they? Which projects are important and how do they relate to the others? Which repos and docs are up-to-date?)

What do we need to do?

High priority:

1. Write a new introductory guide that focuses on what IPFS is doing conceptually, explaining how addresses and lookups and the DAG work. It should use the CLI as an concrete example of these things rather than the other way around, as the current getting started guide does. (#60)

2. Build a concepts dictionary that provides a brief and clear overview of major concepts in IPFS. (#56)

   • Some examples:
     • https://qri.io/docs/datasets/
     • Items under the “concepts” heading in Stellar’s docs, e.g: https://www.stellar.org/developers/guides/concepts/accounts.html (disclosure: I worked on this)
     • Slack sort of does this with the “app features” category in the docs sidebar: https://api.slack.com (they’re somewhere between conceptual and tutorial, and may or may not be more detailed than we want to need to be)

3. Link to (not necessarily embed) our best existing reference docs and major repos (#59)

4. link to (not necessarily embed) our best existing example projects (e.g. https://github.com/ipfs/js-ipfs/tree/master/examples) (#59)

5. Clean up the problems in GitHub organization that make things hard to find: #54, #55, #57, and some parts of #53)

6. Design a site layout that can accommodate the above and launch it :) (#36?)

Note that 3 & 4 are about linking and not about embedding docs. I think we should focus on getting links to what we’ve already got (we have a lot of stuff) first. Simply having the docs site serve as an index to all the things that would be useful but people aren’t finding is incredibly helpful and relatively quick to do.

This is way more minimal than the expansive set of content currently described in #36, but that was half a year ago, so I it might make sense to focus on something smaller for now.

Later:

(To be clear, I think things below like improving existing API docs is much less important than #53 — giving people a clear picture of the status and direction of various APIs and concepts. Developers are getting by, though with plenty of trouble, with what they’ve got. But nothing solves the “where is this going and how should I think about using/not using it?” question for them. Addressing that in some form is critical.)

Not necessarily in any order:

• Add some brief narrative/introductory guides on using go-ipfs, js-ipfs, *-ipfs-api as libraries.

• Document how all the various sub-libraries relate to each other and to the top-level libraries (i.e. go-ipfs and js-ipfs). (Covering these relationships is one of the major missing pieces in a lot of the READMEs.)

• Improve the REST API docs with more detailed information about arguments (many are missing) and example input/output. More than one person was blown away by how useful the docs in interface-ipfs-core were compared to the REST API or Commands docs, which they had been depending on.

• Start to generate/embed API docs from all the code projects.

• Create guides/tutorials for common use cases

  • Archiving big datasets
  • Hosting your web site
  • Dynamic data & (web) apps
  • Securing content
  • Storing/referencing data in non-file data structures (e.g. IPLD)

@dignifiedquire Could you give me some rights to this repo so I can assign things to people.

We get a constant stream of questions about certain topics -- in emails, Github Issues, conversations on IRC, face-to-face exchanges, etc. This is a sign that we need to do a better job of documenting these topics, putting answers in the places where people will find them, and providing ways to follow ongoing work in these areas.

Topics to Document

We should check each of these off when the volume of queries about the topic drops near zero, which will be a sign that either people are finding answers elsewhere or the topic is no longer important.

• Deleting Content You've Added to IPFS -- especially Right to Be Forgotten - see ipfs/blog#112
• Private Content -- limiting who can read/decrypt the stuff you've published on the IPFS network - see ipfs/blog#115
• Private Networks -- limiting which nodes/peers you will even talk to. This limits which peers can see what you've added to your IPFS node and limits which nodes you will provide blocks to - see ipfs/blog#114
• Making content Persist on the Network -- How to get the content to stay on the IPFS network after your machine disconnects - see ipfs/blog#113

If you can think of any other under-documented topics, please say so in the comments on this issue.

Things we can Do to Address This

Some things we must to in order to reduce the volume of queries:

• Establish clear documentation to address the topic
• Publish links to that documentation places where people are looking
• Provide inroads for people to engage in, or follow, ongoing design/development efforts
• Gather ideas from the community about other ways to answer these questions or other channels for broadcasting the answers

Currently the “docs” link on ipfs.io links to docs for http api. Very hard to find the docs/specs for core api

The plan:

1. Make a landing page README in https://github.com/ipfs/interface-ipfs-core/tree/master/API that provides a clear path into the documentation for all the modules
2. Update the readme in https://github.com/ipfs/interface-ipfs-core/ to call out the fact that there are docs, include a link to /API/README.md
3. Update ipfs.io/docs to include a link to the core API docs

ipfs-inactive/interface-js-ipfs-core#66

ref: ipfs/kubo#1952

• Introduction
• Getting started
  • Browser addon
  • go-ipfs
  • js-ipfs
  • Examples/tutorials
• References
  • Commands
  • Core API
  • go-*
  • js-*
• Concepts
  • The IPFS stack
  • Decentralized web
  • Pinning
  • Addressing
  • Protocol-first approach and upgrade path
  • DWeb maturity model
  • Confidentiality and privacy
• Features
  • File system
  • Name system / IPNS
  • Block/object store
  • Data integrations/bridges
  • Graph database
  • Private networks
  • Network transports
  • Pubsub
  • Overlay network / relay
  • HTTP-to-IPFS gateway
  • FUSE mounting
  • Incentivization / FileCoin
• Decentralized apps
  • Data structures
  • Graph traversal
  • Privacy
  • Collaborative editing
  • Messaging / pubsub
  • Wiki
  • Search
  • Video streaming
  • Gaming and VR
  • Blockchains
• Data storage / archival
  • Performance
  • Datastore engines
  • IPFS Cluster
  • Durability guarantees
  • Garbage collection
  • Load balancing
  • Monitoring
  • Deployment
  • Backups
  • Content policies
• Censhorship circumvention
  • TODO
• Case studies
  • PeerPad
  • IPFS in the datacenter
  • Circumventing censorshop in Catalunya
  • Dataset mirrors
• FAQ
• Glossary
• Changelogs

We want to generate static searchable API docs for all relevant go- libraries.

Surprisingly there's no tool for this yet, one might appear in golang/go#2381 (comment) though.

@diasdavid I would be happy to be the PM for this sprint. I have been the PM for the test-lab sprint but I'm sure that I'm doing a very good job. My goal with the IPFS community is to stay involved and spend as much time as I can. However, I spend about 50 hours a week writing code on a project that pays the bills. If my work as PM on the test-lab was acceptable then I'm ready go. If you think someone else could do a better job then thats OK as well. Just let me know.

Developers who are building things on top of IPFS have pretty much all indicated that they’ve solved a lot of their problems by digging through IPFS source code and through the repos here on GitHub. We won’t have perfect docs for them tomorrow, but one quick and easy thing we can do is make sure every repo has a description. A lot of them don’t:

IPFS

• https://github.com/ipfs/js-datastore-core Issue: ipfs/js-datastore-core#11
• https://github.com/ipfs/go-ipfs-cmdkit Issue: ipfs/go-ipfs-cmdkit#20
• https://github.com/ipfs/go-ds-badger Issue: ipfs/go-ds-badger#16
• https://github.com/ipfs/go-block-format Issue: ipfs/go-block-format#10
• https://github.com/ipfs/ipfs-ds-convert Issue: ipfs/ipfs-ds-convert#10
• https://github.com/ipfs/ci-sync Issue: ipfs-inactive/ci-sync#10
• https://github.com/ipfs/kubernetes-ipfs Issue: ipfs-inactive/kubernetes-ipfs#50
• https://github.com/ipfs/jenkins-libs Issue: ipfs/jenkins-libs#8
• https://github.com/ipfs/go-sbs (No readme) Needs deprecation (see #54 (comment)).
• https://github.com/ipfs/go-cid-utils (Completely empty repo) This was deleted.
• https://github.com/ipfs/ipld-unixfs (Empty readme) PR: ipld/legacy-unixfs-v2#8
• https://github.com/ipfs/go-ipfs-archived (Empty readme) Issue: ipfs/go-ipfs-archived#1
• https://github.com/ipfs/go-metrics-prometheus (No readme) Issue: ipfs/go-metrics-prometheus#2
• https://github.com/ipfs/go-metrics-interface (No readme or description) Issue: ipfs/go-metrics-interface#1
• https://github.com/ipfs/go-ipns Issue: ipfs/go-ipns#7
• https://github.com/ipfs/go-ipfs-config Issue: ipfs/go-ipfs-config#1

Libp2p

• https://github.com/libp2p/pubsub-notes
• https://github.com/libp2p/go-xtp
• https://github.com/libp2p/go-libp2p-interface-pnet
• https://github.com/libp2p/go-libp2p-pnet
• https://github.com/libp2p/go-libp2p-dummy-conn
• https://github.com/libp2p/js-libp2p-record
• https://github.com/libp2p/js-libp2p-crypto-secp256k1
• https://github.com/libp2p/js-libp2p-circuit
• https://github.com/libp2p/go-libp2p-identify
• https://github.com/libp2p/go-flow-metrics
• https://github.com/libp2p/go-buffer-pool
• https://github.com/libp2p/go-conn-security
• https://github.com/libp2p/go-conn-security-multistream
• https://github.com/libp2p/go-reuseport-transport
• https://github.com/libp2p/go-libp2p-transport-upgrader

IPLD

• https://github.com/ipld/ipld-examples
• https://github.com/ipld/js-ipld-eth-tx
• https://github.com/ipld/js-ipld-eth-trie
• https://github.com/ipld/js-ipld-eth-account-snapshot
• https://github.com/ipld/js-ipld-eth-block-list
• https://github.com/ipld/js-ipld-eth-storage-trie
• https://github.com/ipld/js-ipld-eth-tx-trie
• https://github.com/ipld/js-ipld-selector
• https://github.com/ipld/js-ipld-git
• https://github.com/ipld/ipld-yang
• https://github.com/ipld/go-ipld-daghelpers

We need to take libp2p, list all our dependencies under the stack and check:

• There's a meaningful Readme with our standard badges
• There's Godoc documentation which is not empty (and passes Golint)
• Follow up on old issues

Currently the “docs” link on ipfs.io links to docs for http api. It's very hard to find the docs/specs for core api.

At the very least, it should link to the info in https://github.com/ipfs/interface-ipfs-core/tree/master/API

We need to decide if we want to move discussions to discourse. If not then we need to take it off the table.

See also:

• original discussion Discourse - Better community building ipfs/community#69
• Discourse: Evaluation Checklist ipfs/community#213
• *.ipfs.io domain for discourse ipfs-inactive/ops-requests#33
• Try out discourse.org for Community Forums ipfs/community#190
• Merge ipfs/ipfs, ipfs/community and ipfs/pm ipfs/community#191

Action Items:

• get discuss.ipfs.io subdomain set up
• collect implementation factors -- "to host or not to host"
• gather list of pros + cons
• plan to phase out the github repositories

• List all the function calls on the main README
• Add examples to each call on the spec ipfs-inactive/interface-js-ipfs-core#124
• List all the function calls on js-ipfs README
• List all the function calls on js-ipfs-api README
• List all the calls that are not documented yet.

It is quite requested.

Right now, there is no place for introducing the different areas where people can figure out how to contribute. The people that should be the target for this is people who want to contribute to IPFS but they don't know the ecosystem yet, and are not sure where their contributions would be the most valuable.

Things that we could do:

• Have webpage that dynamically fetches issues with the tag "difficulty-easy" or other tags that indicates that this issue would be simple to fix
• Write which areas we're currently having the most problems with/most bugs in
• Show other areas where we always appreciate contributions
• Applications that can be written as demo material
• Provide areas where we need help with testing

Some existing guides, would be nice to have a combination of all these features on one page:

• https://www.docker.com/contribute
• https://bugzilla.mozilla.org/buglist.cgi?quicksearch=sw:%22[good%20first%20bug]%22&limit=0
• https://www.joshmatthews.net/bugsahoy/
• http://www.firsttimersonly.com/
• https://www.codetriage.com/
• https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md#getting-started
• https://gohugo.io/community/contributing/
• https://github.com/pouchdb/pouchdb/blob/master/CONTRIBUTING.md
• https://github.com/pouchdb/pouchdb/blob/master/TESTING.md
• https://starters.servo.org/
• https://github.com/servo/servo/blob/master/docs/HACKING_QUICKSTART.md
• https://whatcanidoformozilla.org/
• https://wiki.mozilla.org/Contribute
• https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Introduction

This will be satisfied when

• Everything is in motion towards finding a person to be the full-time owner of docs as a product
• We have a plan around what this person will be doing
• We have a plan for making "docs creation/management" part of our culture

There will be sprint prep meeting held to discuss the upcoming DOCS sprint. Let's shoot for:

Friday 10-Mar 17:00 UTC.

Notes: https://hackmd.io/GzDGCZgDgZnBaApgM1AE3gFhgBlPAQwE5ENwBWKcggI2GQHYGiYg

This meeting should last between 30 minutes to an hour.

Errors and timeouts on the gateway are way too obscure. Even something as simple as a 404 sounds scary: "Path Resolve error: no link named "foo" under Qmdf6iGuPoQ7jmGM48nWoy46F5EwMiXYVif968cpwQXDrU".

We can make these a lot more friendly and useful for seeing how ipfs works. (And just nicer to debug.)

• Gateway should be extracted into ipfs/go-ipfs-gateway
• Gateway needs refactoring to cleanly distinguish errors
• Implement ipfs/go-ipfs-gateway#5

Outdated things like multidaddrs that are not valid anymore, in presentations and other material

We should have a guide on installing ipfs, updating it, and the best practices (and troubleshooting) therein.

@victorbjelkholm This was assigned to you from here https://github.com/ipfs/docs/blob/master/meeting-notes/2017-03-03-pre-prep-call.md. Could you add some details to this.

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.

libp2p module organization, naming conventions & readmes unification

As suggested in https://discuss.ipfs.io/t/libp2p-status-of-go-version-vs-js-version let's make a features matrix for the go and js (and possibly other) implementations of IPFS, libp2p, etc. I'll take lead on making this happen.

This will also give us the impetus to provide a clearer representation of how all the libraries fit together.

cc @whyrusleeping @diasdavid @mishmosh

The next Docs sprint standup will be held on:

Wednesday 03/15/2017 17:00 UTC

This meeting should last 30 minutes. Each sprint member should give a short description of what they are working on and include any roadblocks they are facing.

Just so we don't lose track of stuff (I am already). Please post new stuff as you open PRs.

• multiformats/go-multistream#15 -- Fix and improve example. Add Gx instructions. Golint.
• multiformats/go-multihash#50 -- improve example, link to godoc, make golint happy
• libp2p/go-libp2p#186 -- go-libp2p documentation effort
• libp2p/go-libp2p#185 -- Libp2p examples
• ipfs/js-ipfs#791 -- Tutorial: transfer-files
• ipfs-inactive/website#171 -- Add instructions on how to use ipfs-update and how to upgrade
• ipfs/fs-repo-migrations#59 -- Update README and run.md guide
• libp2p/specs#10 -- Add inital PNet spec

This issue has a bounty!

Successfully closing this issue by producing a production-ready piece of documentation can earn you not only the undying love of the IPFS community — it can net you a financial reward. See the current list of bounty issues and their values here.

The need in brief

Create a glossary that provides a brief and clear definition of major concepts in IPFS, plus links to longer explainers when they exist. Note that we will be pulling these definitions into hover-style tool tips in the future, so please keep definitions fairly brief and written in such a way that the first n characters can be excerpted into a complete tool tip.

Regarding future use in tool tips: Visual design work has already been done on this effort. Please see #372 for mockups and resulting discussion; it'll help you determine how best to proceed with excerpting tool-tip content.

Below are initial terms to seed with. Please add others as you see fit. See as well prior art for “concepts and terms that trip people up”.

• DWeb
• DHT
• Graph
• DAG
• Merkle Tree/DAG
• Merkle “Forest”
• Hash
• Gateway
• Pinning
• Transport
• Swarm
• Information Space
• MFS
• UnixFS (lots of confusion out there on whether this is the same or different from MFS)
• (Cryptographic) Signing
• Peer
• Peer ID
• CRDT
• Repo
• DataStore
• Node, Daemon
• CID (v0, v1, …)
• Path/Address
• DNSLink
• CBOR
• Bitswap
• Blocks
• Bootstrap Node
• Listening
• Dialing
• Announcing
• Relay
• GC/Garbage Collection
• Pubsub
• Filestore
• IPLD (and selectors)
• Libp2p
• Multihash
• IPNS
• SFS
• Blockchain
• Bittorrent
• GraphSync
• pubsub
• filestore
• IPLD
• Libp2p
• multihash
• IPNS
• SFS
• Blockchain
• Bittorrent
• IPLD Selectors
• GraphSync

Deliverable

Content should take the form of a Markdown document. File locations should be as follows:

• MD content should live here (lease make a PR against the existing placeholder document) https://github.com/ipfs/ipfs-docs-v2/blob/master/docs/concepts/glossary.md
• Images, if appropriate, can live in the MD content's parent directory; we'll move them before final merge
• For videos, just post temporarily on the platform of your choice, and we'll sort out on a case-by-case basis

Guidelines

• Please use the IPFS Docs Contributor Guidelines as your north star — adherence to these guidelines are crucial when it comes to awarding potential bounty!
• Also, please keep in mind our core user personae. If a piece of content serves one or more personae in particular, make sure it checks out with that persona's attributes.

So that the draft-to-production path is as short as possible.

Use an "FAQ" tag to flag threads that have good answers to common questions. Consider rewriting the titles of those threads to be appropriately descriptive -- often the good threads have completely unrelated or confusing titles.

Developers who are building things on top of IPFS have pretty much all indicated that they’ve solved a lot of their problems by digging through IPFS source code and through the repos here on GitHub. Unfortunately, a huge proportion of repos there are deprecated, but not clearly marked as such (gray, red, and possibly many of the orange lines in that spreadsheet), making that job much harder.

We won’t suddenly have perfect docs that solve all of their problems tomorrow, so we should coming up with a standard way of marking out deprecated repos that we can easily and quickly apply:

• Have a standard indicator/text in the repo description
• Have a standard indicator/text at the start of the readme
• Think about a policy for when/how to archive repos (makes them read-only and hides them from most listings)
• Apply it to all repos that should be deprecated.
• Also think about the same things for repos that are “in hibernation.” (And should any of those be deprecated instead?)

I’d suggest:

• Description always starts with “DEPRECATED:”
• Readme title always starts with “DEPRECATED:”
• Immediately below the readme title there should be a bold or italicized paragraph about:
  • Why it was deprecated
  • When it was deprecated
  • Where to go for the same resource/functionality/whatever now (if applicable)

(Edit: surfacing our final decisions here so they are easy to find)

Conclusions/Final Process

• Add the topic deprecated to the repo (pulling this over from #57)
• Prefix the repo’s description with “DEPRECATED:”
• Prefix the README title with “DEPRECATED:” (If a repo does not have a readme or its readme is empty, add one with the title: “DEPRECATED: [repo name]”
• Follow the README title with a paragraph describing:
  • Why it was deprecated
  • When it was deprecated
  • Where to go for the same resource/functionality/whatever now (if applicable)
• Finally, if a repo is dead, archive it (but don’t delete it). A dead repo might be ipfs.js, while a non-dead, non-archived one might be newsletter, where we might bring it back in the future.
  • Why archive? links still work, but this hides it from most views and lists on GitHub, drastically reducing noise and confusion. For repos like support, this also prevents people from posting new issues.
  • Downsides: issues and discussions get frozen. We may want to preserve that functionality on some repos (e.g. ones that are freshly deprecated or that haven’t gained any traction/that we can’t support, but that we might want to revisit later).

Checklist of Repos to Fix

Definitely deprecated repos:

• https://github.com/ipfs/starlog
• https://github.com/ipfs/examples
• https://github.com/ipfs/faq
• https://github.com/ipfs/http-api-spec
• https://github.com/ipfs/go-blocks
• https://github.com/ipfs/go-commands
• https://github.com/ipfs/js-ipfs-merkle-dag
• https://github.com/ipfs/support
• https://github.com/ipfs/newsletter
• https://github.com/ipfs/datatogether
• https://github.com/ipfs/ipfs-mans Issue: ipfs-inactive/ipfs-mans#1 (comment)
• https://github.com/ipfs/dnslink-deploy Dead according to @victorbjelkholm
• https://github.com/ipfs/go-sbs (I confirmed this is deprecated with @Kubuxu)
• https://github.com/ipfs/go-cid-utils Nobody seems to have anything to say on this and the repo is completely empty, with no issues or anything, so maybe we should just delete it.

Things that might be dead, but need clarity from their owners/maintainers:

• https://github.com/ipfs/astralboot
• https://github.com/ipfs/bitswap-ml Shutting down and merging with research-bitswap? Readme/description pretty opaque. Deprecated according to @whyrusleeping
• https://github.com/ipfs/dataviz
• https://github.com/ipfs/fs-stress-test
• https://github.com/ipfs/go-iprs
• https://github.com/ipfs/refs
• https://github.com/ipfs/refs-denylists-dmca
• https://github.com/ipfs/file-browser
• https://github.com/ipfs/install-go-ipfs
• https://github.com/ipfs/scala-ipfs-api
• https://github.com/ipfs/apps Only one issue has discussion in the past 6 months and this issue: ipfs/apps#37 suggests the discussions here should be happening in other places instead
• https://github.com/ipfs/golang-build Not used according to @victorbjelkholm
• https://github.com/ipfs/refs-solarnet-storage
• https://github.com/ipfs/project-repos Several folks didn’t even know the site this powers existed
• https://github.com/ipfs/POST
• https://github.com/ipfs/ops-requests
• https://github.com/ipfs/go-dnslink
• https://github.com/ipfs/connections-globe (Not used in WebUI, which has its own version)
• https://github.com/ipfs/paperhub
• https://github.com/ipfs/go-key Not used according to @whyrusleeping
• https://github.com/ipfs/go-ipfs-gateway
• https://github.com/ipfs/2016-Q3-Workshop
• https://github.com/ipfs/js-idb-pull-blob-store Only used by js-ipfs-merkle-dag, which is deprecated
• https://github.com/ipfs/go-ds-redis
• https://github.com/ipfs/go-ds-lru
• https://github.com/ipfs/ipfs-pages
• https://github.com/ipfs/websiter
• https://github.com/ipfs/js-level-pull-blob-store
• https://github.com/ipfs/go-ds-s3
• https://github.com/ipfs/test-lab Open issue on converging with other test tools: ipfs-inactive/pm-test-lab#28
• https://github.com/ipfs/research-bitswap Dead according to @whyrusleeping
• https://github.com/ipfs/ipfs-netjournal
• https://github.com/ipfs/contributors-hex-grid
• https://github.com/ipfs/contributors
• https://github.com/ipfs/ipfs-nodeschool
• https://github.com/ipfs/jest-environment-aegir
• https://github.com/ipfs/glossary (Issue: ipfs-inactive/glossary#1 (comment))
• https://github.com/ipfs/go-ipfs-path (deleted since it was never actually in use)
• https://github.com/ipfs/go-ipfs-path-resolver (deleted since it was never actually in use)
• https://github.com/ipfs/go-ipfs-blockservice (deleted since it was never actually in use)

Already archived, but missing standard notices: (How much do we care to update?)

• https://github.com/ipfs/ipfs-web-app
• https://github.com/ipfs/go-ipld
• https://github.com/ipfs/js-libp2p-ipfs-nodejs
• https://github.com/ipfs/js-libp2p-ipfs-browser
• https://github.com/ipfs/ipfs.js
• https://github.com/ipfs/browserify-zlib-next
• https://github.com/ipfs/js-docker-base
• https://github.com/ipfs/node-github-issue-bot
• https://github.com/ipfs/dweblink-infra

Turned out not to be dead:

• https://github.com/ipfs/js.ipfs.io (2018-06-04 Per @diasdavid, this now has active work)
• https://github.com/ipfs/ipfs-hubot (Magically risen from the dead once someone pointed it out)

Right now it's a pain to deploy new examples because they're spread across multiple repos, and there's no tooling to simplify this.

Ideally, the website build process pulls in the blog, examples, and example-viewers repos.

Update the documentation to clarify how are these related

• http api
• core-interface (aka common interface)
• etc.

Put that info into the main landing places where people seek API documentation (ie. https://ipfs.io/docs)

This is not about multiformats and libp2p, but about the components that make up the upper part: IPFS.

• fs-repo
• exchange
  • blockstore
    • datastores
  • bitswap
• data structures
  • ipld
  • dag-pb / merkledag
  • unixfs
• dnslink
• fs path / dweb link
• ipns
• gateway

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.

We want to improve the js-ipfs init sequence and we have a clear vision of how that should happen that has been discussed here: ipfs/js-ipfs#556

This requires writing code, but it will greatly simplify the documentation of using a js-ipfs node. I believe it will be valuable for this Sprint. I can tackle it :)