It’s possible I am an idiot, too. Just throwing it out there. While I do work at such a pace where skimming is how I read normally, it’s not that the writing style was incompatible with my reading style. In fact, I do remember seeing that manual setup is preferred, but it didn’t sit right. I just didn’t get it.
For one, I didn’t really get how the dependencies were already setup by that point - like I expected postgres to need a password, but it was set in an env file at a later step? I know so little about postgres, but I would think a database engine would need some type of admin level credentials to be setup.
Then there was the part about the docker setup claiming it was “default”, which is a type of preferred solution in the sense the software developers preferred to make it default, so then why would those same developers recommend a different solution? Pretty conflicting to say the least, so I chose the path of least resistance, or so I thought.
Finally, and this was the worst part - the document flow was all off. It didn’t read like a process. It read like a choose your own adventure story without the instructions to go to what page at the end of the section. Check out the outline:
# Developing Plasmic Studio: getting started
## Database setup
## OS-specific instructions
### Mac OS X
### Ubuntu 18.04+
## asdf
## Docker setup
## Manual setup (suggested)
### 1. Environment variables
### 2. Installing dependencies
### 3. Seeding the database
### 4. Application setup
### 5. Starting dev servers
## Using the app
## Troubleshooting
### Executable `hadolint` not found
### tools/dev.bash: line 3: concurrently: command not found
## Next steps
The Docker Setup is on the same level as Database setup and OS-specific Instructions, which are not required for the Docker Setup, even though they are required for the hybrid and/or manual setups. I did some of the OS-specific instructions randomly, just in case. That’s the cautious idiot in me.
Here is my suggestion:
# Developing Plasmic Studio: getting started
## Choose Your Setup
### Hybrid Setup (recommended)
1. Database setup
a. Mac OS X
b. Ubuntu 18.04+
c. Windows 10+
2. Applicable Manual Setup Steps**
### Manual Setup (difficult, resource light)
1. OS-specific instructions
a. Mac OS X
b. Ubuntu 18.04+
c. Windows 10+
2. asdf instructions
3. Environment variables
4. Installing dependencies
5. Seeding the database
6. Application setup
7. Starting dev servers
### Docker Setup (easy, resource heavy)
1. Mac OS X
2. Ubuntu 18.04+
3. Windows 10+
## Using the app
## Troubleshooting
### Executable `hadolint` not found
### tools/dev.bash: line 3: concurrently: command not found
## Next steps
**Choose your own adventure with the page turn instructions.
You could flatten the structure a little bit if the options were really clear:
# Developing Plasmic Studio: getting started
## Choose Your Setup
### Hybrid Setup (recommended)
### Manual Setup (difficult, resource light)
### Docker Setup (easy, resource heavy)
## Option 1: Hybrid Setup
### Database setup
1. Mac OS X
2. Ubuntu 18.04+
3. Windows 10+
### Applicable Manual Setup Steps**
## Option 2: Manual Setup
### OS-specific instructions
1. Mac OS X
2. Ubuntu 18.04+
3. Windows 10+
### asdf instructions
### Environment variables
### Installing dependencies
### Seeding the database
### Application setup
### Starting dev servers
## Option 3: Docker Setup
### Mac OS X
### Ubuntu 18.04+
### Windows 10+
## Using the app
## Troubleshooting
### Executable `hadolint` not found
### tools/dev.bash: line 3: concurrently: command not found
## Next steps