Is Scoped Help really Helping?

[nothingismagick]

ipfs/interface-ipfs-core/SPEC

has hands down, the best documentation anywhere in the IPFS ecosystem - coupled with testing and using examples right from the tests - cheers to the js core-devs!!! This is what I expected to see in a world-class project like IPFS. I just wonder why it took me so long to find it - oh yeah, there are over 150 repos and I was advised (perhaps incorrectly?) to focus on go-ipfs...

The title of this issue is "Help Scoping" - and is a bit of a reflection on my first experiences with go-ipfs - I am taking the time to write this right now because I know that as my experience grows, so too will fade my fond memories of days where all I could say was: WTF why?

There are several times when people will need help in this kind of project, but I will focus on just one in this issue:

• IPFS Virgins
  This is where a clear, simple, current and useful tutorial is needed. Something that shows EXACTLY how to set up and run ipfs and its dependencies, including concise examples of useful things AND dangerous dragons (such as that dastardly server setting...) https://ipfs.io/docs/install/ tries to do this, but has many mistakes. The biggest mistake IMHO is that there is NO mention of the js-ipfs version here, which is a massive fail. Especially considering the amazing addition of the KEY spec, which is entirely unavailable to go-ipfs users at the moment.
  Another fail is that ipfs update install will, by the way, NOT upgrade - contrary to what the doc says. To upgrade you need to call ipfs update install latest. It is trivial compared with the server dragon, but how did I find that out? ipfs update --help? No. I should have been paying closer attention and written ipfs update install --help- but I didn't think to drill down into more docs.

$ ipfs update install $(ipfs update versions | sed '$!d')

# As a matter of embarrassing fact, I actually wrote this one-liner 
# before I looked at the code - because I was bothered by a typo-
# graphical mistake and wanted to make a pull-request to fix it...

So what is the point and what do I mean with scoped help? Scoped help is context-aware information that the user can interpret to make a better decision about how to execute code. Because there is no man ipfs page, the information I trust is the stuff that the --help flag gives me. I am so used to it, that I blindly trust what I see there...

When used as an additional method to drill down into the details of commands, scoped help can be extremely "helpful" in making an informed decision. However, if scoped help is the only help that is immediately available, then chances are good that users won't see ipfs update install latestand other core-devs and doc-writers will incorrectly explain that merely invoking ipfs-update install is enough to actually upgrade the ipfs version. Scoped help is good, but it creates a lot of internal technical debt and external confusion.

ENDNOTE

For the record, this is what I pieced together from multiple places (including multiple ipfs repos, issues, stack overflow, godocs etc.) to setup and start go-ipfs on ubuntu 16.4 including bash completion...

#!/usr/bin/env bash

# ~/.ipfs/ipfs-cluster-setup.sh
# ubuntu 16.4 go-ipfs setup geschizzle

wget https://storage.googleapis.com/golang/go1.10.linux-amd64.tar.gz
sudo tar -C /usr/local -xvf go1.10.linux-amd64.tar.gz

export GOPATH=$HOME/go
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
export PATH="/usr/local/go/bin:$PATH"

go get -u -d github.com/ipfs/go-ipfs
cd $GOPATH/src/github.com/ipfs/go-ipfs && make install
mkdir ~/.ipfs/
cp misc/completion/ipfs-completion.bash ~/.ipfs/
source ~/.ipfs/ipfs-completion.bash

go get -u -d github.com/ipfs/ipfs-cluster
cd $GOPATH/src/github.com/ipfs/ipfs-cluster
make install

echo 'source ~/.ipfs/ipfs-completion.bash' >> ~/.bash_completion
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
echo 'export PATH=$PATH:$GOROOT/bin:$GOPATH/bin' >> ~/.bashrc
echo 'export PATH="/usr/local/go/bin:$PATH"' >> ~/.bashrc

go get -u github.com/ipfs/ipfs-update
ipfs update install latest
ipfs init profile server

bash ~/.ipfs/ipfs-cluster-startup.sh & disown
exit 0

This is what I use to start up the daemon & bootstrap its cluster (with nohup and writing the PID to command line and to a /tmp file

#!/usr/bin/env bash

# ~/.ipfs/ipfs-cluster-startup.sh
# (do not bootstrap the bootstrapper!)
# chmod a+x this script!

cluster_secret=$1
bootstrap=$2
nohup ipfs daemon &> /dev/null & disown
pid=$!
echo $pid > /tmp/ipfs.pid
echo "ipfs daemon started\n/tmp/ipfs.pid ${pid}"
if [ ! -f ~/.ipfs-cluster/service.json ]; then
    # doing it this way cuz apparently without ipfs running cluster can't init, 
    # but the docs aren't clear on this. Would prefer to have it in the setup script
    ipfs-cluster-service init -s ${cluster_secret}
fi
nohup ipfs-cluster-service --bootstrap "${bootstrap}" -f &> /dev/null & disown
pid=$!
echo $pid > /tmp/ipfs-cluster.pid
echo "ipfs-cluster started\n/tmp/ipfs-cluster.pid ${pid}"

[nothingismagick]

@Mr0grog @flyingzumwalt @ZenGround0 - What do you think?

[Mr0grog]

Thanks for taking the time to try and write this all up instead of just leaving. 😬

I know there are a lot of issues with docs and explaining to people just how all the pieces of IPFS are supposed to work or be used, so we definitely appreciate you working your way through it.

a clear, simple, current and useful tutorial is needed. Something that shows EXACTLY how to set up and run ipfs and its dependencies, including concise examples of useful things AND dangerous dragons

I’m hoping to rewrite that tutorial in a better way that hits a little of this and explains what is actually going on when you run various commands on IPFS. There’s a rough outline here: #60 (comment) Does that get at a lot of what you’re thinking?

I know it certainly won’t cover everything; there are issues across the board that can’t all be covered in an introductory explainer. We’ve talked about also having:

• A few use-case targeted guides (like “Running an IPFS pinning service/IPFS on a server and making it fast”

• Documentation of the major concepts involved in IPFS and how to make use of them ([NEW CONTENT] [BOUNTY] Glossary #56)

there is NO mention of the js-ipfs version [in the getting started tutorial], which is a massive fail. Especially considering the amazing addition of the KEY spec, which is entirely unavailable to go-ipfs users at the moment.

Go-ipfs actually does have key; the interface-ipfs-core repo’s documentation is also not perfectly up-to-date or accurate. Most of the places where it says “WIP” for Go means the documentation is a work in progress, not the implementation (I know, that’s completely unclear). Most of these docs are variously missing parts or not up to date in different ways, so one of the major tasks at hand is to organize and understand all that we’ve got (#59) and then figure out how to reformulate that into fewer, better docs that we can keep accurate and up-to-date.

If you’d like to help write any of those docs or give feedback on them as they’re authored, keep an eye on this repo.

Another fail is that ipfs update install will, by the way, NOT upgrade

It seems like there is some good discussion and forward progress happening over at ipfs/kubo#4880 (comment), so I think that’s the right place to focus for this issue.

I trust is the stuff that the --help flag gives me. I am so used to it, that I blindly trust what I see there

It’s good to know that you’re running into lots of issues and we are all trying to improve things. If you are able to make some more specific comments on problems in the help text or suggest new text, we are all really open to issues and PRs to fix it in go-ipfs and js-ipfs. Please do that if you can!

this is what I pieced together from multiple places to setup and start go-ipfs on ubuntu 16.4 including bash completion…

Thanks. We’ll talk through this with go-ipfs and ipfs-cluster folks as we start to work on #62. There’s a lot of docs work to do, though, so I don’t know how soon you’ll see a definitive document on that. We’re doing our best at starting to improve the situation.

[nothingismagick]

I know Rome wasn't built in a day - and if I can help then I will. Right now I consider this process to be a matter of due-diligence and open-source good-samaritanship. The more I run up against road-blocks the better I understand things. Kind of like a blind person moving into a new house and painfully learning where all the walls, doors and chairs are. After a while it should stop being painful. The issues I am posting are merely just the echoes of someone bouncing off of the walls...

[Mr0grog]

OK. I’m going to close this for now under the assumption that we’ve got other issues linked where we are trying to address all the actionable stuff here. Thanks!