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

Better section naming and organization #8

Merged
merged 9 commits into from
Aug 15, 2023

Conversation

netsettler
Copy link

@netsettler netsettler commented Aug 12, 2023

  • Remove a useless link to the "Overview" on the first page.
  • Make the heading for "Basic Setup" to be "Installing Prerequisites", since that naming is more standard.
  • Rename the "Getting Started" option to more standard "Using submitr", since getting started is ambiguous between installation and usage.
  • Add an "Implementation of submitr" heading on the implementation part to make it clear to end users they don't need to look at this.
  • Reorganize to make experimental rclone support not be the first thing that you see in this doc, since non-experimental stuff needs to be first.
  • Make rclone section not pretend to tell you about awscli in the heading, since the actual text barely mentions awscli.
  • Light editing on the opening of the section about rclone to make the motivational part clearer.

NOTE TO REVIEWERS:

You can preview this by downloading the repo and doing

make preview-locally

That will build an html set in docs/html/ (which I've made invisible due to .gitignore) and will open a browser to view it.

… see in this doc, and to make it not pretend to tell you about awscli in the heading since the actual text barely mentions awscli. Remove a useless link to the overview on the first page.
docs/source/index.rst Outdated Show resolved Hide resolved
Awscli/Rclone Submission (experimental)
=======================================
===================================
Using rclone instead (experimental)
Copy link

Choose a reason for hiding this comment

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

Consider dropping this section from the documentation entirely for the time being. I don't believe we're looking to utilize rclone in this fashion for SMaHT (via a publicly available bucket), though I know we're looking at the possibility of integrating the tool at some point.

Copy link
Author

Choose a reason for hiding this comment

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

Yeah, that's fine with me. This section is available in the CGAP documentation. Maybe I can rearrange the CGAP documentation in this same way and just leave it there. Did it make more sense in that context, or ought it be removed there as well? For tentative removals, I just rename files to whatever.DISABLED and I can do that rather than deletion if you're uncertain as to whether we'd want to later add it back in one or the other context).

Copy link

Choose a reason for hiding this comment

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

It made sense in the context of CGAP, so I think rearranging there is a good idea. Disabling for this repo is best for now to prevent possible miscommunication with SMaHT folks until we have settled the issue.

Copy link
Author

Choose a reason for hiding this comment

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

Great. That's what I'll do then.

@netsettler netsettler merged commit c15ad24 into master Aug 15, 2023
3 checks passed
@netsettler netsettler deleted the kmp_better_section_organization branch September 26, 2023 21:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants