ethersphere / swarm-guide

Swarm Documentation

Swarm Guide

This repository has been archived

The documentation source can now be found under: https://github.com/ethersphere/swarm/tree/master/docs/swarm-guide

swarm-guide's Issues

swarm-guide POC3 review: FUSE & manifests

@holisticode please review the following documentation chapters:

• FUSE
• Manifests

Below is a list of criteria to give better guidelines on what we should look for when reviewing the documentation in order to focus efforts in the right direction.

--

Language criteria:

• Plain words: Extent to which the vocabulary is easily understood
• Readability: Ease with which the reader can follow the argument of the text

Design criteria:

• Graphic elements: Use of tables, bullet lists, graphs, charts, diagrams - if a diagram is missing - please open an issue describing what needs to be done

Structure criteria:

• Quality of the chapter's organisation in relation to its function
• Impression: Attractiveness and approachability of the document’s overall appearance

Relationship criteria:

• Audience: Appropriateness to the knowledge and skills of the users

Content criteria:

• Relevance: How relevant the content is to the recipient
• Correctness: Are the commands that are in use up-to-date?
• Action: Clarity about what action is required of the user

Please submit all PRs to swarm-guide/docs-overhaul branch.
If there are any blockers - please address them within the scope of this issue.

swarm-guide POC3 review: introduction & configuration

@justelad please review the following documentation chapters:

• introduction
• configuration

Below is a list of criteria to give better guidelines on what we should look for when reviewing the documentation in order to focus efforts in the right direction.

--

Language criteria:

• Plain words: Extent to which the vocabulary is easily understood
• Readability: Ease with which the reader can follow the argument of the text

Design criteria:

• Graphic elements: Use of tables, bullet lists, graphs, charts, diagrams - if a diagram is missing - please open an issue describing what needs to be done

Structure criteria:

• Quality of the chapter's organisation in relation to its function
• Impression: Attractiveness and approachability of the document’s overall appearance

Relationship criteria:

• Audience: Appropriateness to the knowledge and skills of the users

Content criteria:

• Relevance: How relevant the content is to the recipient
• Correctness: Are the commands that are in use up-to-date?
• Action: Clarity about what action is required of the user

Please submit all PRs to swarm-guide/docs-overhaul branch.
If there are any blockers - please address them within the scope of this issue.

gettingstarted: Wrong information for private swarm

In the section "running a private swarm" it's written that:

First you fire up a number of swarm instances, following the instructions above. You can keep the same datadir, since all node-specific info will reside under $DATADIR/bzz-$BZZKEY/ Just make sure that you create an account for each instance of swarm you want to run.

However, if you try to do this, you get the error:

Fatal: Error starting protocol stack: datadir already used by another process

Setting the --ipcpath explicitly to a different ipc file does not help.

I presume the documentation's expectations here are wrong?

Installing from source part not complete

If a naïve user follows the instructions of this section, she would encounter dependency problems while installing geth. This would be helped by replacing go install with go get.
However, it might be better just to reference the corresponding part of geth documentation rather than repeating it here.

correct documentation errors

in manifests there's the following example:

swarm --recursive --defaultpath orange-papers/index.html --bzzapi http://swarm-gateways.net/ up orange-papers/ 2> up.log

2477cc8584cc61091b5cc084cdcdb45bf3c6210c263b0143f030cf7d750e894d

where swarm --recursive --defaultpath orange-papers/index.html uploads a single file, but it should probably be swarm --recursive --defaultpath orange-papers/

$DATADIR not compatible with --testnet

There is an inconsistency in the docs as to which data directory to use and where the keystore is.

If we start geth with --datadir=X --testnet then the actual datadir will be X/testnet.
Swarm on the other hand doe s not add a /testnet subdirectory so we will have to specify its datadir as X/datadir. Thus there is confusion because $DATADIR is not the datadir.

I suggest we do away with the variable $DATADIR entirely and just spell it out at /path/to/data/. It makes it easier to understand (but harder to copy-paste).

Also there is a difference between geth account new and geth --testnet account new!

Simplify introduction

The introduction and "basics" section in the documentation is too long and too complicated. We should cater for the reader who is wondering about how to migrate from web2 to web3, who should be able to read an overview in 5 minutes and understand most of what is written. With the current text, I don't think that's at all the case.

Ideally the swarm page would whet the apetite with slogan claims, the introduction/basics should elaborate briefly on key topics that are clearly labelled and recognizable from the homepage. Anything more elaborate should be in the architecture section.

swarm-guide POC3 review: up/downloading and getting started

@nolash please review the following documentation chapters:

• uploading and downloading
• getting started

Below is a list of criteria to give better guidelines on what we should look for when reviewing the documentation in order to focus efforts in the right direction.

--

Language criteria:

• Plain words: Extent to which the vocabulary is easily understood
• Readability: Ease with which the reader can follow the argument of the text

Design criteria:

• Graphic elements: Use of tables, bullet lists, graphs, charts, diagrams - if a diagram is missing - please open an issue describing what needs to be done

Structure criteria:

• Quality of the chapter's organisation in relation to its function
• Impression: Attractiveness and approachability of the document’s overall appearance

Relationship criteria:

• Audience: Appropriateness to the knowledge and skills of the users

Content criteria:

• Relevance: How relevant the content is to the recipient
• Correctness: Are the commands that are in use up-to-date?
• Action: Clarity about what action is required of the user

Please submit all PRs to swarm-guide/docs-overhaul branch.
If there are any blockers - please address them within the scope of this issue.

more examples in PSS documentation

PSS documentation is now better, but needs elaborated examples so that users can understand how to interact and work with it.
Consider giving examples using a library that supports it, such as erebos

ref #58

revisit roadmap and update it accordingly

our roadmap that we link to from the new documentation is out of date.
the last status updates are from 2017 and we should update it with relevant information for users to take seriously.

optionally we should link to our ethersphere project roadmap kanban board and make it publicly accessible with read-only permissions so that users could explore and see our progress in real-time.

add links to orange papers

sw3 games
wip - https://www.sharelatex.com/read/yszmsdqyqbvc

• pdf

network
wip - https://www.sharelatex.com/read/gxhwssqzgfpr

• pdf

Wrong instructions in manual connect (--nodiscover)

--nodiscover flag is not implemented anymore. This section needs to be updated to instruct how to manually control connection. It should also be made clearer that it doesn't give full control of connectivity, only of the boostrapping.

https://swarm-guide.readthedocs.io/en/latest/gettingstarted.html#adding-enodes-manually

Pending tasks for doc

• link to code docs for PSS
• link to code docs for MRU
• proper usage guide for FUSE, pending on ethersphere/swarm#542
• section on sample dapps
• architecture chapter second half to be restructured
• RPC section intro needed to explain the RPC t comms options

path variables in doc

Issue

path examples mostly come from Linux(?), intermediate mac users will be baffled.

examples (section):

• .bashrc vs .bash_profile (2.2.2)
• "$HOME/Library/Ethereum/" vs "$HOME/.ethereum/" (3.2; there is now a note for this there, could be moved up to the top)

Proposed solution

docs could use path variables all through (eg $DATADIR etc). section 2. could set them up in a table like this:

path	LINUX	macOS	etc
GOPATH	$HOME/go	$HOME/go
PATH	...
DATADIR	...
...	...

it could add that

• swarm has been tested on Linux and macOS (there's already a note)
• mac users should avoid using "~"
• advanced users could save the variables to their bash profiles,
  • and that if you don't know what that is, you should skip this, but then you have to set the vars up every time.

Unable to connect http://swarm-gateways.net

When trying to connect to this url It will loading for a long time and no response.

formatting in sphinx

dfn: seen in text, should be control :dfn:

Incorrect usage for swarm cli

http://swarm-guide.readthedocs.io/en/latest/usage.html

swarm up --bzzapi http://swarm-gateways.net /path/to/file/or/directory

returns error with swarm 1.5.6-unstable.

Incorrect Usage.

up [arguments...]

"upload a file or directory to swarm using the HTTP API and prints the root hash",

flag provided but not defined: -bzzapi

it worked with the command below by putting up before the path

swarm --bzzapi http://swarm-gateways.net up /path/to/file/or/directory

either the document or the cli should be fixed.

swarm-guide POC3 review: encryption & bzz schemes

@gbalint please review the following documentation chapters:

• Encryption
• BZZ Schemes

Below is a list of criteria to give better guidelines on what we should look for when reviewing the documentation in order to focus efforts in the right direction.

--

Language criteria:

• Plain words: Extent to which the vocabulary is easily understood
• Readability: Ease with which the reader can follow the argument of the text

Design criteria:

• Graphic elements: Use of tables, bullet lists, graphs, charts, diagrams - if a diagram is missing - please open an issue describing what needs to be done

Structure criteria:

• Quality of the chapter's organisation in relation to its function
• Impression: Attractiveness and approachability of the document’s overall appearance

Relationship criteria:

• Audience: Appropriateness to the knowledge and skills of the users

Content criteria:

• Relevance: How relevant the content is to the recipient
• Correctness: Are the commands that are in use up-to-date?
• Action: Clarity about what action is required of the user

Please submit all PRs to swarm-guide/docs-overhaul branch.
If there are any blockers - please address them within the scope of this issue.

add links to videos

see ethersphere/swarm-home#17
and the existing listing on swarm home

make html-docker fails, because sphinx-build command is not found

I run make html-docker as per the documentation. It returns this error message:

Makefile:13: *** The 'sphinx-build' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the 'sphinx-build' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/. Stop.

architecture chapter: explain saturation depth better

swarm-guide POC3 review: MRU & Encryption

It is not clear at the moment whether MRU is able to function in encrypted mode per description in:

https://github.com/ethersphere/swarm/wiki/Symmetric-Encryption-for-Swarm-Content

A small paragraph clarifying if yes/no, or any other details would be helpful.

Pss api reference, pss flag no longer available

7.3.2
"pss methods are by default exposed via IPC. If websockets are activated on the node, they will also be available there if the pss module is explicitly specified."

As I see --pss is no longer needed as it's loaded automatically (atleast with --ws).

"pss methods are by default exposed via IPC. If websockets are activated on the node, they will also be available there."

make html fails, because could not import extension sphinx_tabs.tabs

I activated a virtualenv (Python 2.7.15rc1, pip 19.0.2). Then installed sphinx as per the documentation. Running make html prints this error message:

Running Sphinx v1.8.4
Extension error:
Could not import extension sphinx_tabs.tabs (exception: No module named sphinx_tabs.tabs)

installation: Install swarm binaries section is missing

swarm-guide POC3 review: architecture & api reference

TBD review the following documentation chapters after other chapters have been done:

• Architecture (already reviewed once by @zelig and @homotopycolimit)
• API Reference - to be reviewed after all other chapters have been reviewed and updated accordingly with the information gathered while doing so

Below is a list of criteria to give better guidelines on what we should look for when reviewing the documentation in order to focus efforts in the right direction.

--

Language criteria:

• Plain words: Extent to which the vocabulary is easily understood
• Readability: Ease with which the reader can follow the argument of the text

Design criteria:

• Graphic elements: Use of tables, bullet lists, graphs, charts, diagrams - if a diagram is missing - please open an issue describing what needs to be done

Structure criteria:

• Quality of the chapter's organisation in relation to its function
• Impression: Attractiveness and approachability of the document’s overall appearance

Relationship criteria:

• Audience: Appropriateness to the knowledge and skills of the users

Content criteria:

• Relevance: How relevant the content is to the recipient
• Correctness: Are the commands that are in use up-to-date?
• Action: Clarity about what action is required of the user

Please submit all PRs to swarm-guide/docs-overhaul branch.
If there are any blockers - please address them within the scope of this issue.

Sphinx build warnings

Problem

• When compiling the html Sphynx lists a series of warnings. The compiled docs look fine, but I'm not sure whether the warnings can be ignored.

Steps to reproduce problem

make html

Error logs

• In logs, I replaced my GOPATH with $GOPATH.

$GOPATH/src/github.com/swarm-guide/contents/apireference.rst:5: WARNING: Duplicate explicit target name: "npm".
$GOPATH/src/github.com/swarm-guide/contents/apireference.rst:5: WARNING: Duplicate explicit target name: "npm".
$GOPATH/src/github.com/swarm-guide/contents/apireference.rst:5: WARNING: Duplicate explicit target name: "github".
contents/usage/mru.rst <included from $GOPATH/src/github.com/swarm-guide/contents/usage.rst>:4: WARNING: Content block expected for the "note" directive; none found.
contents/usage/mru.rst <included from $GOPATH/src/github.com/swarm-guide/contents/usage.rst>:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
contents/usage/manifests.rst <included from $GOPATH/src/github.com/swarm-guide/contents/usage.rst>:96: WARNING: Title level inconsistent:

Path Matching
^^^^^^^^^^^^^^
contents/usage/manifests.rst <included from $GOPATH/src/github.com/swarm-guide/contents/usage.rst>:119: WARNING: Title level inconsistent:

Paths and directories
^^^^^^^^^^^^^^^^^^^^^
contents/usage/fuse.rst <included from $GOPATH/src/github.com/swarm-guide/contents/usage.rst>:41: WARNING: Title level inconsistent:

Mount
^^^^^^^^
contents/usage/fuse.rst <included from $GOPATH/src/github.com/swarm-guide/contents/usage.rst>:75: WARNING: Title level inconsistent:

Access
^^^^^^^^
contents/usage/fuse.rst <included from $GOPATH/src/github.com/swarm-guide/contents/usage.rst>:79: WARNING: Title level inconsistent:

Unmount
^^^^^^^^
contents/usage/fuse.rst <included from $GOPATH/src/github.com/swarm-guide/contents/usage.rst>:92: WARNING: Title level inconsistent:

List Mounts
^^^^^^^^^^^^^^^^^^
$GOPATH/src/github.com/swarm-guide/contents/usage/bzz.rst:4: WARNING: duplicate
warning: duplicate label bzz protocol suite, other instance in $GOPATH/src/github.com/swarm-guide/contents/usage.rst
$GOPATH/src/github.com/swarm-guide/contents/usage/bzz.rst:74: WARNING: duplicate label bzz-raw, other instance in $GOPATH/src/github.com/swarm-guide/contents/usage.rst
$GOPATH/src/github.com/swarm-guide/contents/usage/ens.rst:4: WARNING: duplicate label ethereum name service, other instance in $GOPATH/src/github.com/swarm-guide/contents/usage.rst
$GOPATH/src/github.com/swarm-guide/contents/usage/mru.rst:4: WARNING: Content block expected for the "note" directive; none found.
$GOPATH/src/github.com/swarm-guide/contents/usage/mru.rst:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] usage/mru
$GOPATH/src/github.com/swarm-guide/contents/architecture.rst:268: WARNING: undefined label: bzz url schemes (if the link has no caption the label must precede a section header)
$GOPATH/src/github.com/swarm-guide/contents/architecture.rst:277: WARNING: undefined label: manifests (if the link has no caption the label must precede a section header)
$GOPATH/src/github.com/swarm-guide/contents/architecture.rst:280: WARNING: undefined label: bzz url schemes (if the link has no caption the label must precede a section header)

Expected behaviour

• no errors.

Note

• These errors seem to come from the docs not following the sectioning/labelling conventions for reST. Might just be visual clutter.

swarm-guide POC3 review: installation and ens chapters

@nonsense please review the following documentation chapters:

• installation and updates
• ENS chapter

Below is a list of criteria to give better guidelines on what we should look for when reviewing the documentation in order to focus efforts in the right direction.

--

Language criteria:

• Plain words: Extent to which the vocabulary is easily understood
• Readability: Ease with which the reader can follow the argument of the text

Design criteria:

• Graphic elements: Use of tables, bullet lists, graphs, charts, diagrams - if a diagram is missing - please open an issue describing what needs to be done

Structure criteria:

• Quality of the chapter's organisation in relation to its function
• Impression: Attractiveness and approachability of the document’s overall appearance

Relationship criteria:

• Audience: Appropriateness to the knowledge and skills of the users

Content criteria:

• Relevance: How relevant the content is to the recipient
• Correctness: Are the commands that are in use up-to-date?
• Action: Clarity about what action is required of the user

Please submit all PRs to swarm-guide/docs-overhaul branch.
If there are any blockers - please address them within the scope of this issue.

Create API documentation

For the http and the command line API

Lingering bzz-resource scheme

See https://swarm-guide.readthedocs.io/en/latest/usage.html#bzz-resource

It's not clear how to use feeds as a mutable addresses.

From reading docs, I understood that if I don't want to use ENS, but have a mutable address I can use feeds. This, fortunately, turned out to be true.

But I had to dig through some source code to find, what exactly needs to be published.

The answer: "0x1b20${hash}"

References:

• https://multiformats.io/multihash/#the-multihash-format
• https://github.com/ethereum/go-ethereum/blob/e187711c6545487d4cac3701f0f506bb536234e2/swarm/multihash/multihash.go#L27-L28

Documentation consistency

Label use

• have a setup of thing name (acronym) (link to discussion) for first mentions and acronyms for subsequent mentions in s9
• maybe everywhere?

Comb together warnings / notes

• bring together separate warning boxes if they refer to the same thing

Parallelise discussion where needed

• e.g. s2 installation

current issues with doc

• http://swarm-docs.s3-eu-west-1.amazonaws.com/up-and-download.html#adding-entries-to-a-manifest this needs proper examples
• swarm-docs.s3-eu-west-1.amazonaws.com/up-and-download.html#downloading-swarm-content-from-your-local-node swarm down should be part of the CLI ethersphere/swarm#439
• http://swarm-docs.s3-eu-west-1.amazonaws.com/up-and-download.html#tar-stream-upload this should have explanation/text
• http://swarm-docs.s3-eu-west-1.amazonaws.com/userguide.html#fuse FUSE section is incorrectly under resource updated (install FUSE appears in the sidebar )
• FUSE need explanation, text
• PSS - there is no example, user doesn't even know how i can interact with this component
• cross referencing
  • between usage and API ref
  • CLI and http for upload/download
  • etc
• Introduced in POC 0.3, symmetric encryption using SHA3 Keccak256 is ...... putting the concepts of plausible deniability and censorship resistence to work. this makes no sense like this
• the entire confifguration section contains outdated stuff. how come.
• why are the private and singleton modes in the config section? Not sure i like this reorganisation .
• URL schemes are duplicated in the doc, but first it says: Swarm offers 8 distinct URL schemes. No it is 6, deprecated stuff should go
• all thigs with SWAP should go until we got it done
• why is encryption a separate section while MRU and FUSE are hidden under working with content
• what is this duplicate http://swarm-docs.s3-eu-west-1.amazonaws.com/apireference.html#bzz-schemes doing in the API ref section

Default use case should be at the top

At the top of the how-to-use-swarm section should be the default swarm connected to testnet paired with geth on ropsten.
Only later should we introduce the options of running your own network, singleton mode and the rest.
Many (most?) users start at the top of the documentation and work their way down.
I have already answered many questions from people somewhat lost with a --verbosity(6) --maxpeers(0) setup coming from the docs.

swarm-guide POC3 review: PSS & MRU

@janos please review the following documentation chapters:

• PSS
• Mutable Resource Updates

Below is a list of criteria to give better guidelines on what we should look for when reviewing the documentation in order to focus efforts in the right direction.

--

Language criteria:

• Plain words: Extent to which the vocabulary is easily understood
• Readability: Ease with which the reader can follow the argument of the text

Design criteria:

• Graphic elements: Use of tables, bullet lists, graphs, charts, diagrams - if a diagram is missing - please open an issue describing what needs to be done

Structure criteria:

• Quality of the chapter's organisation in relation to its function
• Impression: Attractiveness and approachability of the document’s overall appearance

Relationship criteria:

• Audience: Appropriateness to the knowledge and skills of the users

Content criteria:

• Relevance: How relevant the content is to the recipient
• Correctness: Are the commands that are in use up-to-date?
• Action: Clarity about what action is required of the user

Please submit all PRs to swarm-guide/docs-overhaul branch.
If there are any blockers - please address them within the scope of this issue.

add swarm dapp tools/libs into the doc

• https://www.npmjs.com/package/swarmgw swarmgw node package