Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Add Nebari installation guides and getting-started as first directions #45

Merged
merged 55 commits into from
Jul 5, 2022

Conversation

viniciusdc
Copy link
Contributor

@viniciusdc viniciusdc commented Jun 16, 2022

resolves #36

I am opening this PR to gather feedback and help decide on content organization/details/etc.

This PR added the following:

  • Documentation related to different Nebari install options: HPC, Cloud, and Local
  • Detailed deployment guides for each supported cloud provider for Nebari Cloud
  • A Getting Started section on the sidebar and menu to better direct first (admin) users on how to install Nebari and where to go after it -- please think of this as a "symlink" to better situate the first users, not as a break of the Diatexis organization
  • There will also be a tutorial on how to set Local for testing (Minikube will be replaced in the future)

@viniciusdc viniciusdc added area: documentation 📖 status: in progress 🏗 This task is currently being worked on content: doc/how-to Diatiaxis - how to content: doc/tutorial Diataxis - tutorial labels Jun 16, 2022
@netlify
Copy link

netlify bot commented Jun 16, 2022

Deploy Preview for nebari-docs ready!

Name Link
🔨 Latest commit 3c01f4e
🔍 Latest deploy log https://app.netlify.com/sites/nebari-docs/deploys/62c48093f4f72c000be1876b
😎 Deploy Preview https://deploy-preview-45--nebari-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

@viniciusdc viniciusdc requested a review from kcpevey June 16, 2022 00:52
@viniciusdc
Copy link
Contributor Author

Remaining tasks:

  • Fix current missing pieces from previous docs
  • Populate docs with rewritten step-by-step documentation
  • What level of detail should we give the user about the cloud provider options?
  • Should we explain in more depth the process of generating cloud credentials besides pointing to external links/docs?
  • Expand the advanced configuration
  • Add explanations related to 'nebari-config.yaml'
  • Expand cloud provider specific details in the yaml config

docs/docs/how-tos/nebari-aws.md Outdated Show resolved Hide resolved
docs/docs/how-tos/nebari-aws.md Show resolved Hide resolved
docs/docs/how-tos/nebari-azure.md Outdated Show resolved Hide resolved
docs/docs/how-tos/nebari-azure.md Show resolved Hide resolved
docs/docs/how-tos/nebari-aws.md Outdated Show resolved Hide resolved
docs/docs/started/deploy.md Outdated Show resolved Hide resolved
docs/docs/started/deploy.md Outdated Show resolved Hide resolved
docs/docs/started/installing-nebari.md Outdated Show resolved Hide resolved
docs/docs/started/troubleshooting.md Outdated Show resolved Hide resolved
docs/sidebars.js Outdated Show resolved Hide resolved
@trallard trallard added the type: enhancement 💅🏼 New feature or request label Jun 20, 2022
docs/docs/how-tos/nebari-aws.md Outdated Show resolved Hide resolved
docs/docs/how-tos/nebari-azure.md Outdated Show resolved Hide resolved
docs/docs/how-tos/nebari-azure.md Outdated Show resolved Hide resolved
docs/docs/how-tos/nebari-azure.md Outdated Show resolved Hide resolved
Co-authored-by: Tania Allard <[email protected]>
@trallard
Copy link
Member

trallard commented Jul 4, 2022

@trallard can you explain this? Are you asking if these "getting started" docs replace the quickstart? If so, then I'd say no, they don't. nebari-dev/nebari#18 is what I envision as the quickstart. What are your thoughts?

I am not saying that these replace the others - but the "sections" on the sidebar and the navbar - it is confusing having two sections that are seemingly the same (unless one has to go to the actual sections to see why these are different)
We still need a Nebari 101

We are following diataxis, but its very common to still have a top level "getting started" page exposed.

I am not sure I follow - these getting started sections fill in that section so not sure if we need yet another "getting started" we should have these + the Nebari 101 under the same category

For us, that actually means we need two "getting started" pages - one for an admin, and one for end user.

not really - since we are not using personas we do not need these - we need to cover the tasks these folks would need to achieve but that might mean 1, 2, 3 or as many as needed "getting started"-type docs

This is the comment I mentioned - https://github.com/nebari-dev/nebari/pull/45/files#r912518272

it is not about replacing the content but "renaming" and consolidating directories

@kcpevey
Copy link
Contributor

kcpevey commented Jul 4, 2022

@viniciusdc reminder to run pre-commit run --all-files one last time since new pre-commits just made it into main

@kcpevey
Copy link
Contributor

kcpevey commented Jul 4, 2022

From @trallard 's comments:

  • Move all of your files that are in /started/* into /getting-started/*
  • Nebari-101.md, quickstart.md, and the quickstart sidebar can be removed for now.
    • Nebari-101.md will be completed by this and will go into the getting-started section

docs/docs/started/cloud-providers.md Outdated Show resolved Hide resolved
docs/docs/started/cloud-providers.md Outdated Show resolved Hide resolved
docs/docs/started/installing-nebari.md Outdated Show resolved Hide resolved
docs/docs/started/troubleshooting.md Outdated Show resolved Hide resolved
docs/sidebars.js Outdated Show resolved Hide resolved
@viniciusdc viniciusdc requested a review from trallard July 5, 2022 18:14
@viniciusdc viniciusdc removed the needs: changes 🧱 Review completed - some changes are needed before merging label Jul 5, 2022
@kcpevey
Copy link
Contributor

kcpevey commented Jul 5, 2022

Looks great! I didn't do another complete read through since I was already happy with the wordings, but I confirmed that the getting-started folder structure is in alignment with what I believe @trallard wanted to see.

Copy link
Member

@trallard trallard left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok merging now. Thanks a lot @viniciusdc

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
Status: Done 💪🏾
Development

Successfully merging this pull request may close these issues.

[DOC] - How to install Nebari
5 participants