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

entry index.rst mods. #206

Merged
merged 1 commit into from
Sep 19, 2024
Merged

entry index.rst mods. #206

merged 1 commit into from
Sep 19, 2024

Conversation

larrybabb
Copy link
Contributor

  • replaced hardcoded latest links with relative links
  • removed Site map (not needed IMO)
  • improved presentation of bulleted list of sections
  • updated Copyright year

* replaced hardcoded latest links with relative links
* removed Site map (not needed IMO)
* improved presentation of bulleted list of sections
* updated Copyright year
@larrybabb
Copy link
Contributor Author

@mbrush here's my first bit of feedback on your docs. I just focused on the index.rst landing page. mostly technical, main takeaway here is Do NOT use static references to latest RTD sections, use relative links within the doc so folks don't inadvertantly switch to a different RTD instance unknowingly. I also think we should discuss how to "slim" things down or re-org so that it's not so overwhelming to folks coming in for the first time.

I think we should consider an "Appendix" and embed several of the later sections under it so that it doesn't look like so much. We should also consider NOT putting in any sections that are "COMING SOON" as my experience is that it leaves folks feeling like it is unfinished and they loose interest and motivation to proceed much quicker.

I think it's fine to carve out a plan for the "missing" sections, but you can add them when they emerge instead of trying to predict. Less is more. And only provide sections if you have something to offer. If you want to put a "What's coming?" section in the appendix and discuss the "To be developed or coming attractions" stuff that's fine.

So please look over this draft and if you like it we can merge it. I can help go through the remaining portion of the doc and fix up the hardcoded lnks with relative ones if you want.

@larrybabb larrybabb marked this pull request as ready for review September 19, 2024 04:12
@larrybabb
Copy link
Contributor Author

@mbrush BTW in case you forgot you can view the RTD build for this PR under the "Show all checks" link above and then drill into the last check for the RTD build. You'll find the "View Docs" button soon after.

@mbrush mbrush merged commit 05e3da5 into 1.x Sep 19, 2024
3 checks passed
@larrybabb larrybabb deleted the lbabb-rtd-intro-feedback branch September 19, 2024 21:38
@mbrush
Copy link
Contributor

mbrush commented Sep 20, 2024

Thanks @larrybabb . Still new to RTD so I didn’t know about the relative reference feature. Will update pages and use this going forward.

As for slimming and re-organizing - agreed, and working on this, and would love your input. I had planned on something more concise for the first pass - but it kinda snowballed and I just needed to get something up for connect. That said, I don't necessarily think there is too much content overall - maybe could just be organized better. Again, I'd love to hear your thoughts here.

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