New contributor documentation thoughts

[Vectornaut]

Overview

When I first got started with Backscope, I was asked to jot down thoughts on the documentation from my perspective as a new contributor. Here's a mostly-unedited dump of those notes, as requested. Most of the friction points described here are pretty minor. They're ordered roughly chronologically, rather than by severity.

Quick start

It would be nice to hear about the Ubuntu installation guide more up front!

"The GNU multi-precision arithmetic dev package"

• Is this libgmp-dev or libgmp3-dev on Ubuntu? (Answered in Ubuntu installation guide.)

The source venv/bin/activate example used here is inconsistent with the slightly differently-named directory .venv in environment creation example.

Install PostgreSQL

I initially assumed this link would lead to PostgreSQL documentation. It took me some time to notice that it was actually Backscope documentation.

I might be useful to mention the createdb step here too

Installing backscope on Ubuntu

"Note that you will likely need at least 4GB of memory RAM in order to build and install backscope and its dependencies."

• This really threw me, because I have less than 4 GB of disk space available.

Activate the virtual environment

• I feel more comfortable when things like this include explicit undo instructions. In this case, that would mean instructions on how to deactivate the virtual environment—even if it's as simple as closing the terminal session.

How to check whether PostgreSQL is installed could be helpful. My biggest time loss was figuring out that the package postgresql wasn't actually installed.

sudo -u postgres

• More explanation of what this does might be useful

"You may use any name for the user"

• I spent a few mintues trying to understand what controlled the username in the command below

sudo -u postgres createuser --interactive

• I could've used expectations for the results of this command. Here's a copy of the results I got.

Enter name of role to add: backscope
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n

The built-in Bash syntax highlighting made ALTER USER look like comment, which confused me.

Emphasize no address when setting authentication method?

Resetting the database

I think these commands need to be run as the postgres user.

init_db_instructions.txt

http://127.0.0.1:5000/get_sequence/A0001

• This endpoint call no longer works.

[katestange]

Here's a spelling error:

backscope/doc/install-postgres.md

Line 46 in a63d3cf

SECRET_KEY="Uneccessary for development"

[gwhitney]

Quick start

It would be nice to hear about the Ubuntu installation guide more up front!

I tried to make this more prominent in #96. @Vectornaut how does that look?

[Vectornaut]

@gwhitney—It's definitely more prominent than before! Personally, my eye is first drawn to the numbered list, so I'd lobby for something even more prominent, like subsection headings:

Ubuntu users

You may prefer these detailed, step-by-step instructions. They've been tested for [latest Ubuntu version, like you suggested], and they could perhaps also be tailored to other Linux distributions or other operating systems.

All operating systems

1. Install Git if need be and clone this repo...

[gwhitney]

Ubuntu users

You may prefer these detailed, step-by-step instructions. They've been tested for [latest Ubuntu version, like you suggested], and they could perhaps also be tailored to other Linux distributions or other operating systems.

At the risk of bikeshedding, to my eye that makes Ubuntu too prominent in the main README for a package that really doesn't have any intrinsic OS dependency, let alone distro dependency. If, as you say, the eye is drawn to the numbered list, how about if we make the first item in that list simply be a pointer to the more detailed instructions?

[Vectornaut]

That makes sense! Another suggestion, which preserves the parenthetical while also putting "Ubuntu" in a place where it seems more likely to be seen:

All users can follow this general quick-start guide.

(Ubuntu users can also start here. These detailed step-by-step instructions have been tested for [latest Ubuntu version], and they could perhaps also be tailored to other Linux distributions or other operating systems.)

1. Install Git if need be...