Spoke: Feature Request: Split readme into more actionable chunks

[nke5ka]

Problem
The readme file has multiple mutually exclusive instruction sets. This may be confusing to users who want to just use the software without having to edit it, and is also confusing to developers who want to setup locally. Additionally, the readme is getting more fractured and has an almost non-linear flow

Solution
My proposal is to split the readme into multiple pages. The future readme would be focused on background / goal and possibly Heroku one click deployment, with additional documentation for each aspect of background / heroku on separate pages. On the future readme, the local development step is to be placed in its own page, linked to from the readme.

[ibrand]

Sounds like the plan of action would be:

• Pull out the dev env sections from the README and provide a clear link to them (at the bottom? At the top?)
• Create a new doc called HOWTO-set-up-your-environment.md (or a better name?) and move the dev env instructions there
• Link to the new doc from CONTRIBUTING.md

Anything else there? Are there sub tasks here that you feel able to take on?

[sharonsolomon]

@nke5ka is this something you are currently working on? I can take it on as a first project if not.

It could be helpful to include a link and/or content from the 'How to Hire Someone to Deploy Spoke page.'
The first two sections of that page are about how to decide if and how you should use Spoke. That would be helpful to have alongside the different deployment options.

[nke5ka]

Hi @sharonsolomon, feel free to take this on, if @ibrand is okay with it! It would be helpful for any future readers of the page. Apologies for being a bit too busy right now to pick it up, but I hope this will be great first project for you.

[sharonsolomon]

Sounds good @nke5ka ! I'll work on it this week.

[ibrand]

@sharonsolomon Yay!! Would love this help.

[sharonsolomon]

Hoping for feedback on this incomplete draft. I pushed commits to my tree in chunks with explanations of each change and just linked them to this issue via comment. (I feel like there may have been a better way to do that?). Before fixing all the links, etc. I wanted to check in, since this is a fairly major revision. @ibrand @nke5ka @schuyler1d

I am doing the work in https://github.com/sharonsolomon/Spoke/tree/new

Since I am already going through all the links, I can also rename the docs to match the naming convention, if that is something people want.

Remaining
[] fix all internal links
[x] copy-edit
[] review again for flow
[] review list of docs to make sure every page has a link to it

[ibrand]

Wow @sharonsolomon this is looking great and makes me want to mirror your table of contents in: #1760 since these are similar to mine but better. Thank you!!

Looked like a few of the docs in the getting started section don't exist yet. Are those part of your "review list of docs to make sure every page has a link to it" check list item?

[sharonsolomon]

Hi @ibrand. Glad to contribute. I also just joined the slack. Should I start a thread about the readme and docsify projects there?

I still need to review the second half of the main readme page that is just full of links. It looks like I can use a combination of our two structures to do that easily.

And yes- those links are on my to-do list. I just wanted to figure out if people were ok with my names for docs files before adding links to them everywhere.

[sharonsolomon]

@ibrand I had already renamed some other docs locally to help them match the naming conventions. I'll push them now. If folks don't want to rename them I'll revert it.

[sharonsolomon]

Alright, I've finished my attempt at this project, except for reviewing and fixing all internal links.

I am awaiting an ok from whoever gives it (@ibrand @nke5ka) on the file structure and naming. Once I have that I will fix all the links (happy to also fix them in the sidebar at that point). Please let me know if there's anything else that needs changing! Thanks for your support!

Remaining:
[] fix all internal links
[] fix link to microsite (what is it?)
[x] copy-edit
[x] review again for flow
[x- solved by docsify] review list of docs to make sure every page has a link to it

[ibrand]

I'll comment on your PR to main! Thank you for all of this work this really helps make the docs a friendlier and clearer place.

[Frydafly]

Awesome work @sharonsolomon! Is this ok to close? Cc @ibrand

[sharonsolomon]

Awesome work @sharonsolomon! Is this ok to close? Cc @ibrand

Thanks! Fine by me!