Re-organize documentation to match new structure #55
Conversation
- Added docs on authentication methods we support - Split up 'users' docs into 3 separate page, to match different kinds of content - Make docs slightly more verbose in the service of completeness
|
Partial TODO:
|
Moved into howto style content. I left out the bits about 'Last Activity' - it is mostly self-evident, and I'm not sure I want to encourage instructors looking at when students last logged-in!
yuvipanda
force-pushed
the
new-docs-structure
branch
from
8b0a343
to
986a38d
Compare
There was a problem hiding this comment.
Thanks for the improvements here @yuvipanda - in general I like the layout of the documentation and the extra content is very helpful. I made a few suggestions/comments/questions, mostly focused around cross-linking between sections and making the content in general easy to navigate. Happy to go through a few iterations with you here 👍
| period of time (default 1h) are automatically stopped (via | ||
| [jupyterhub-idle-culler](https://github.com/jupyterhub/jupyterhub-idle-culler)). | ||
| This means your notebook server might be stopped for inactivity even if you have | ||
| a long running process in the notebook. This timeout can be configured. |
There was a problem hiding this comment.
We should link to the actual way to configure it, no?
There was a problem hiding this comment.
Yeah, but that requires we add more docs in the pilot-hubs repo for SREs, which doesn't exist atm. I'll add a TODO here
|
|
||
| 2. [*GitHub*](https://github.com/). Extremely popular community of people creating, publishing and collaborating on code. Accounts are free, and many people already have them especially since the target community for most hubs are people who also write some kind of code. | ||
|
|
||
| 3. [*ORCID*](https://orcid.org/). Everyone who has published a paper has one of these, and anyone else can easily sign up. Almost exclusively used by researchers. |
There was a problem hiding this comment.
We should tell people how they can choose one or the other, what is the process by which one is picked? Perhaps here we can just say "when we set up your hub, we'll ask you which type of authentication you prefer".
|
|
||
| 4. ???. We could probably support other authentication providers, depending on your specific needs and the provider's complexity. Please reach out to us if none of these 3 work. | ||
|
|
||
| ## Authorization |
There was a problem hiding this comment.
I think we could have two sections: Authorizing Administrators, and Authorizing Users. Then we explain that administrators are generally authorized via configuration, while users are authorized via the admin panel.
There was a problem hiding this comment.
I've addressed this without splitting it into sections, how does it look?
There was a problem hiding this comment.
I think it's fine, but could we add in "regular users" and "admin users" in bold rather than regular text? I think it's important for documentation to be glance-able. Most people will not read the whole page, they'll have a specific question in mind and they'll quickly glance the page for cues that the answer is there. So I think section headers, or bold text, is a way to give people a hint where a particular topic is covered. Does that make sense?
admin/howto/manage-users.md
Outdated
|
|
||
| ## To remove users | ||
|
|
||
| ???? |
There was a problem hiding this comment.
Do you plan on improving this in the current PR? If not then we should add a comment in the markdown like:
% TODO: document how to remove users
index.md
Outdated
| admin/migrate | ||
| admin/content | ||
| ``` | ||
|
|
||
| ```{toctree} | ||
| :caption: Administrator configuration guides |
There was a problem hiding this comment.
What is the relationship between the configuration guides and the how-to guides? They seem similar to me so trying to figure out why they have two different top-level sections
There was a problem hiding this comment.
That's a good question. I was thinking of configuration guide as a list of all possible options, but that can probably be better written as a how-to guide as well. We can have a separate administrator's reference if need be. I'll try to rewrite them.
There was a problem hiding this comment.
@choldgraf I think configuration options require 2i2c engineer support and how-to guides do not. I've clarified that with subheadings here.
Co-authored-by: Chris Holdgraf <choldgraf@berkeley.edu>
|
@yuvipanda gimme a ping when you're ready for a new review! (or to merge) |
|
@choldgraf Ready for review again! I couldn't figure out how to cross-link pages though :( |
I don't think this is specific enough to us to keep.
#54 has all that information, and is a better fit for a 'howto' section.
|
I've moved the bit about downloading your own data to its own file, and the rest of the 'migrate' documentation should be superseeded by #54. I'm still not sure why links don't work, but otherwise this is good to go! |
|
Oops my bad @yuvipanda - I made some edits and structure improvements, and then I ran Either way, if you're +1 on the changes then I'm also +1 to merge |
|
OK merging this in so that it doesn't become out-of-date when new docs are updated! Thanks @yuvipanda for this great re-organization, and helping to lay a foundation for more docs to come! |
different kinds of content
completeness
Follows 2i2c-org/infrastructure#293
to try and make documentation more coherent.
closes #62