ipfs-inactive / docs Goto Github PK
View Code? Open in Web Editor NEW[ARCHIVED] đ¤ đ IPFS documentation working group, plus IPFS docs site code
Home Page: https://docs.ipfs.io/
License: Other
[ARCHIVED] đ¤ đ IPFS documentation working group, plus IPFS docs site code
Home Page: https://docs.ipfs.io/
License: Other
libp2p module organization, naming conventions & readmes unification
This is not about multiformats and libp2p, but about the components that make up the upper part: IPFS.
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.
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.
@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.
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)
explicit descriptions of go-ipfs and js-ipfs on ipfs.io/docs and their status of interop etc
We should rework the current example and add other examples to libp2p.
go-libp2p interfaces split over multiple packages, these could be moved into the root package
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.
We need to take libp2p, list all our dependencies under the stack and check:
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:
ipfs/research
or ipfs/pm
)And I might mark the repos them this way:
Repo categories:
Labeling:
type-<category>
(e.g. type-discussion
) (EDIT: was previously type:<category>
)Discussion: CRDT Research
The following is based on https://docs.google.com/spreadsheets/d/1IDVAGfniyHCJLIxLc3y7K7YTOFGCtgwTVCZEojtNLlw
Documentation:
Website:
Discussion:
Infrastructure:
Resource:
We need to do some honest research to create a cohesive picture of things like:
âŚwhich should give us a clearer, more concrete picture of what problems we need to solve.
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:
Pandas
what to like:
scikit-learn
what to like:
Django
what to like:
Trac
what to like:
Ceph
what to like:
Angular
what to like:
Others:
MongoDB
git
Chef
Ansible
D3
Further possible actions to take:
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.
So that the draft-to-production path is as short as possible.
Just so we don't lose track of stuff (I am already). Please post new stuff as you open PRs.
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:
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 :)
@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.
@dignifiedquire Could you give me some rights to this repo so I can assign things to people.
Update the documentation to clarify how are these related
Put that info into the main landing places where people seek API documentation (ie. https://ipfs.io/docs)
It is quite requested.
We should have a guide on installing ipfs, updating it, and the best practices (and troubleshooting) therein.
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.
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.
If you can think of any other under-documented topics, please say so in the comments on this issue.
Some things we must to in order to reduce the volume of queries:
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:
Action Items:
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:
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).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?
What do we need to do?
High priority:
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)
Build a concepts dictionary that provides a brief and clear overview of major concepts in IPFS. (#56)
Link to (not necessarily embed) our best existing reference docs and major repos (#59)
link to (not necessarily embed) our best existing example projects (e.g. https://github.com/ipfs/js-ipfs/tree/master/examples) (#59)
Clean up the problems in GitHub organization that make things hard to find: #54, #55, #57, and some parts of #53)
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
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:
Iâd suggest:
(Edit: surfacing our final decisions here so they are easy to find)
deprecated
to the repo (pulling this over from #57)ipfs.js
, while a non-dead, non-archived one might be newsletter
, where we might bring it back in the future.
support
, this also prevents people from posting new issues.Definitely deprecated repos:
Things that might be dead, but need clarity from their owners/maintainers:
Already archived, but missing standard notices: (How much do we care to update?)
Turned out not to be dead:
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
Libp2p
IPLD
Not sure where to place this, so putting it here in the meantime.
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.
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 namestar-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.
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.
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:
Some existing guides, would be nice to have a combination of all these features on one page:
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.
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.
ref: ipfs/kubo#1952
Let's use this issue as a place to gather observations & feedback from newbies.
This is related to #16
Outdated things like multidaddrs that are not valid anymore, in presentations and other material
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
Expect an update on the Q4/2017 work and the plans for Q1+Q2/2018 soon.
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"
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?
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:
I found few documentation engines that may work:
http://www.sphinx-doc.org/en/stable/index.html
reStructuredText markup
- http://www.sphinx-doc.org/en/stable/rest.html
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
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.
This will be satisfied when
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
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.)
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.
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â.
Content should take the form of a Markdown document. File locations should be as follows:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
đ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. đđđ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google â¤ď¸ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.