Onboarding documentation suggestions

[colorful-tones]

Since I'm onboarding and going through the process with a fresh set of eyes/ears. I wanted to jot down some possible suggestions for improving documentation.

All these suggestions should be taken with the context that I'm new to SquareOne and could likely be overlooking the obvious. I do have a good deal of experience working with Mark Jaquith's WP Skeleton (used by SquareOne), Roots - Bedrock, WP Local Docker, and many other local dev tooling setup in the WordPress ecosystem.

Replace all instances of "SquareOne local" with "SquareOne Local", and "SquareOne global" with "SquareOne Global". I think this is causing the biggest noise for me. There are areas where "SquareOne local" is referenced, but since it is lowercase "local" I'm interpreting it as a generic local environment, whereas I believe the author and documentation should be clear as to whether there are two difference products: SquareOne Local and SquareOne Global.

Then, I would reorganize the documentation as follows:

1. Intro to overall terminology and concepts associated with SquareOne (including a clear callout to differentiate SquareOne Global and SquareOne Local).
   • Tools and packages used (links), e.g. Docker, Mark Jaquith WP Skeleton, Gulp, Grunt, test suites, etc. (gives devs a lay of the land)
2. Setup & Usage scenarios:
   1. New user (internal)
      • new project
      • existing project
   2. Contributors
3. Role specific documentation (after setting up)
   • Front end
   • Back end

Also, this was the most enlightening bit of info that I found late in the game when trying to set up: https://github.com/moderntribe/square-one/blob/master/dev/docker/README.md#daily-usage

How to organize your SquareOne instances 👆

I'm hastily jotting this down just to get it down and will be happy to try and contribute enhancements in the noted areas in the coming weeks.

Thanks to all the hard work that undoubtedly numerous developers have contributed to SquareOne. Awesome project!

[colorful-tones]

To give an example of confusion around "SquareOne Local" and "SquareOne Global" can confuse a user.

Here: https://github.com/moderntribe/square-one/blob/master/docs/setup/existing-project.md#configure-dev-domain--ssl

#### Configure Dev Domain & SSL

1. Lookup dev domain that is configured in the `/dev/docker/docker-compose.yml` for `VIRTUAL_HOST=`. 
2. Configure SSL: Run `npm run docker:global:cert DOMAIN.tribe`, where `DOMAIN` is the dev domain.
3. Copy `local-config-sample.json` to `local-config.json` and set the `proxy` value to your domain 

If I am understanding correctly. It might be a bit more clear to state the following:

#### Configure Dev Domain & SSL

1. Lookup dev domain that is configured in the `/dev/docker/docker-compose.yml` for `VIRTUAL_HOST=` in your SquareOne Local project instance.
2. Configure SSL: Run `npm run docker:global:cert DOMAIN.tribe`, where `DOMAIN` is the dev domain in your SquareOne Global project instance.
3. Copy `local-config-sample.json` to `local-config.json` and set the `proxy` value to your domain in your SquareOne Local project instance.

Am I interpreting that correctly?

[Luc45]

@colorful-tones

Yes, that's correct. I agree that can be misleading, thanks for pointing that out.

If you could bring to light any more examples like this that you find, that will be really helpful.

[nickpelton]

Would love a docs PR with the corrections.

[ryanurban]

@Luc45 @colorful-tones did we get these documentation items updated do you know? Thanks!

[colorful-tones]

Unfortunately, I have little to offer here. I do not even have a SQ1 set up anymore.

I would just recommend combing through docs and differentiating SQ1 Local vs SQ1 Global. Those are my assigned terminology and might better terms to distinguish the two, but distinguishing is key takeaway.

[ryanurban]

Fair enough. Thanks! Will ticket as part of our documentation pass to come as part of updated SQ1.