Patchwork freezes on launch if Oasis is already running (because of an SSB server conflict, I assume). I added an FAQ to guide people around that pothole.
The example command `oasis` all by itself wasn't obviously a command-line command, so I added a sentence about it.
Also added a sentence about installing Node, geared at non-technical people.
Problem: A big chunk of both the readme and the startup output is
dedicated to configuration, which feels to me to be focused on
developers and advanced users rather than beginners who just want to try
using Oasis.
Solution: Move readme configuration info to its own file and hide all
config output (except one line) behind `--debug`. While doing this I
noticed that we're `require()`ing a few modules that we don't need
before setting `process.env.DEBUG`, which I've reorganized so that we
don't accidentally disable debug mode for those modules.
Problem: The install instructions in the readme contains quotes because
it has a `*`, but `#semver:` does what we need without the quotes. The
`docs/install.md` file also has some unnecessary complexity, like
cloning via SSH (only useful for maintainers), which I think we can
safely remove.
Solution: Change the install instruction and reorganize
`docs/install.md` to be more relevant to people who are installing from
source.
Problem: The npm registry is great for proprietary modules who need to
ship binaries but not really useful for free and open source software.
It creates a divide between users and our Git repo, and introduces a
for-profit company as an intermediary to distribute Oasis.
Solution: Remove the npm registry as a distribution platform and just
use our Git repository instead. This removes npm registry references
from the readme, instead prioritizing the GitHub repository, and leaves
room for others to mirror the Git repository (for allows us to move to
less-Microsofty Git hosting).
Problem: The roadmap should exist in the issue tracker, not the repo.
Solution: Since all of the roadmap items have been converted into
issues, we're now good to remove the roadmap from the repo.
Problem: The previous readme didn't really have very much information
about what Oasis is or what we want it to be. It wasn't very enticing.
Solution: Zoom out a bit and give a top-3 list of features that
distinguishes Oasis from other social networking applications and SSB
applications in general.
Problem: I didn't really like random text posts from me being in the
readme, and the aspect ratio of the screenshot meant that it ended up
taking up lots of vertical space.
Solution: Use a wide screenshot of some concept art to keep it from
stretching vertically very far while still showing off the absolute
basics of Oasis.
Problem: Help link in readme was pointing to the issue type selection
which is no longer useful because we just have one template.
Solution: Fix the link and point directly to the issue creation link.
Problem: The --offline documentation doesn't mention that networking
status can be changed, which may give the false understanding that the
networking is permanently offline when you use that flag.
Solution: Add a note that mentions that the 'meta' page lets you change
your networking status, and that --offline is only applicable to the
starting state of Oasis.
Problem: I've had a few friends have trouble installing Oasis with an older version of Node.js.
Solution: Add supported versions to the readme in a way that we don't have to update (like version numbers) and link to the Node.js website for people who want to learn more about the release schedule.
Roxie Gibson
Johan Bové
Christian Bundy
KawaiiPunk
Cinnamon
Daan Wynen
Joshua Kelly
Jonathan Dahan
Stephen Solka
Peter Squicciarini