AlexsLemonade / AlexsLemonade/OpenScPCA-analysis
Docs request: "Quick start" guide for technical setup
- Dominant language
- HTML
- Stars
- 16
- Forks
- 24
- Avg merge
- 3d 5h
- Merged PRs (30d)
- 4
Description
### What is the documentation improvement or update you wish to see?
I am opening this issue to suggest we consider adding a form of "quick-start setup" guide for technical setup. We have a lot of documentation spread out for setup over several pages, and it may be easy to get lost in navigating these especially when there's jumping back and forth among pages in potentially disparate parts of the docs.
### Is there any additional context you would like to provide?
This suggestion is brought to you by feedback from our newest contributor @cansavvy while getting set up locally to contribute to OpenScPCA. Specifically, she was getting lost along the way to set up AWS CLI and offered this feedback:
> I think what a little bit throws me off is there's not really a quick start or a linear set of steps I can follow. It's clearly very incredibly thorough but my brain is mush and I am just trying to get going.
She suggested only to add this section, not remove anything existing:
> ...I think keep it as is but have a "quick start" which I'm happy to be the test dummy for. The thoroughness is great but for someone like me who has 0% knowledge on the project its a tad overwhelming
I wondered that [this page](https://openscpca.readthedocs.io/en/latest/technical-setup/) might effectively be the kind of quick-start guide they're looking for, which would suggest we need to do a better job making folks aware of this page. But:
> I was beginning to follow this page yes, and found it quite helpful but then because its full of links I quickly lost it when I had to go to other pages to follow the steps
This suggests all the jumping around _from_ this page makes it unhelpful as a "quick-start" page, since it becomes "not quick" fairly quickly...if you will.
### If this request is for an existing documentation page, please provide the link here.
This generally refers to our technical setup section, but is also related to our "Getting Started" pages which introduce AWS onboarding (but not CLI setup, which is in technical).
Contributor guide
Research direction
Start with the technical setup page and the related Getting Started pages, tracing the linked AWS onboarding and AWS CLI setup instructions. Create a clearly ordered quick-start path without removing the existing thorough documentation; done means a new contributor can follow the setup linearly without repeatedly losing the main page.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100