User Reference Reorganization #1137
Replies: 2 comments 2 replies
-
|
💯 Merging "API" and "Modules" sections in to one section is the only choice that makes sense to me :) I'm not sure I agree one the "single page" approach because I dislike scrolling through really long pages. That's just me, though. It'd be interested to see how users feel! I don't think we need to be rigorous about that, we could ask the question on Zulip as an emoji poll (and remind Slack users to register for Zulip ;) ) Perhaps we can do this in steps: First, move everything in "Modules" into "API", then consider merging everything together. If we do go the single page route, I think we should pay more attention to the headers in that page so the table of contents on the right side of the page is usable as a navigation aid.
100% agree, but I think we should consider these separate efforts. I think they are cleanly separable and parallelizable as the reorganization requires changes to the docs, and improving comprehensiveness requires changing docstrings in the codebase. The reorganization effort is much less work, and I wouldn't like for it to be slowed down by the more expensive effort to be more comprehensive with our docstrings! |
Beta Was this translation helpful? Give feedback.
-
|
How does everyone feel about converting this to an issue? I think it's actionable (prototypable at minimum) |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
The current User Reference organization could improve (unclear when a user should go to API > Search and Access vs. Modules > any nested sub-pages) creating confusion about where the “authoritative” information lives.
Organization of ALL sidebar entries is currently being discussed here: #1133
Function argument details that a user will encounter in other doc pages (e.g.,
cloud_hosted) are located within nested docs (to find 'cloud_hosted', a user needs to go to User Reference > Modules > Collections > Collection Queries). This is just one example, but unless the user is already familiar withearthaccessand how it works, I doubt they would know where to look to find more details on that functionality or understand why things are organized the way they are. Some of the functions within the nested sections also still have "placeholder" text for descriptions... see #597.Here are my recommendations to start the discussion:
Justification:
Users will have one clear, authoritative place to look for functions/ parameters/ defaults, etc. This reduces redundancy, makes the info easy to link to, and makes navigation more intuitive.
What do folks think about this? Again, I am happy to create the issue once some chatter has happened! Any and all jump in, please! ccing a few below.
cc: @andypbarrett @mfisher87 @betolink @asteiker @jhkennedy @danielfromearth
Beta Was this translation helpful? Give feedback.
All reactions