AlexsLemonade / AlexsLemonade/OpenScPCA-analysis

Docs request: "Quick start" guide for technical setup

Open
#948 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.