docs landing page redesign#317
Conversation
Problem: The FAQs page has casual tone with exclamation marks, verbose marketing language in the introduction, and a broken quote mark in the comparison table reference. Simplify emoji usage in header. Condense "What is Flux Framework" introduction to remove marketing phrases like "flexible framework" and "suite of projects". Fix orphaned quote mark and improve phrasing in comparison table reference.
|
Great improvement! |
cmoussa1
left a comment
cmoussa1
left a comment
There was a problem hiding this comment.
This is a great improvement! FWIW, I went to the ReadTheDocs PR build and checked all of the hyperlinks and they seemed to work. I had a couple of super minor comments:
|
|
||
| Flux has similarities to many other resource managers, but we do a variety of things quite differently. | ||
| Check out this comparison table here (:ref:`comparison-table`) for a detailed list!" | ||
| Check out the :ref:`comparison table <comparison-table>` for a detailed list. |
There was a problem hiding this comment.
This could (and probably is) unrelated to this PR, but when the page containing the comparison table is loaded in dark mode, the License row still shows the license names in black text, which makes it pretty difficult to read. Maybe we should flip the font on those license to white when the page is in dark mode.
|
|
||
| Manual Pages | ||
| ------------ | ||
| **For evaluation:** `flux-core <https://github.com/flux-framework/flux-core>`_ |
There was a problem hiding this comment.
Probably just a me-problem, but I'm not sure I quite understand the "for evaluation" prefix here for the link to the flux-core repo. Does "evaluation" in this context mean if the user/admin is interested in actually looking at source code for flux-core? If so, that probably makes sense to me 👍 I'm honestly not even sure what I would suggest otherwise.
There was a problem hiding this comment.
Great point! I think it is supposed to mean just to try things out vs running in production. I'm sure we can come up with something better here. The idea with these links was to give new users an idea of the basic components and their use cases.
There was a problem hiding this comment.
That makes total sense to me! Thanks for explaining that. I'm going to hit approve!
cmoussa1
left a comment
cmoussa1
left a comment
There was a problem hiding this comment.
LGTM! Maybe we should open a separate issue on fixing the font of the licenses when viewing the comparison table in dark mode.
|
BTW, I should probably mention as people notice issues please feel free to directly push them directly to this branch. |
garlick
left a comment
garlick
left a comment
There was a problem hiding this comment.
LGTM! My vote is to move forward without further ado.
|
I've pushed a couple more minor updates here. If the changes are acceptable, I can squash one of the commits down.
|
cmoussa1
left a comment
cmoussa1
left a comment
There was a problem hiding this comment.
This LGTM! IMHO, a very nice improvement to these index pages.
|
Great! I'll squash the incremental changes commit and then set MWP. At some point we should make another pass because there's probably some other low hanging improvements we could make here. |
Problem: The current landing page has a verbose marketing-heavy introduction, poor visual hierarchy, and manual pages buried at the bottom. Users cannot quickly find command references or determine whether Flux meets their needs. Condense initial text to 3 sentences with concrete benefits. Add prominent signpost to flux-core technical docs. Add cards with specific topics for quick navigation and keep the landing page to essential links only. Drop quickstart and leverage flux-core docs instead. Add sphinx-design dependency for card/grid support. Tutorials page: - Remove filler text about other sites potentially having tutorials - Make intro more concise and direct Jobs page: - Add formal job definition from flux-core glossary - Rewrite intro with professional documentation tone - Replace imperative "Learn about" with "This section covers" - Fix capitalization in feedback link This transforms flux-docs into a discovery portal that helps users find the right starting point quickly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Problem: The guides and projects pages use informal language ("Read
more about", "Do you have a question? let us know") that doesn't
match the professional tone established in other first-level pages.
The projects page lacks descriptions for core projects, and
flux-security is incorrectly described as a "plugin".
Update guides/index.rst intro to match formal tone. Add descriptions
to all core projects in projects.rst. Add flux-pmix section. Fix
flux-security description (framework, not plugin) and flux-pmix
description (bidirectional PMIx support).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Merge Queue Status
This pull request spent 31 seconds in the queue, including 5 seconds running CI. Required conditions to merge
|
|
Wow! We really needed this; thanks @grondo! |
|
Ok, merged! Everyone please check out the new site for further improvements, broken links, etc. |
4 participants
I worked through a redesign of the Flux landing page with Claude working as a Ruthless Technical Editor and Opinionated UX Engineer and this is the result.
The landing page is greatly simplified with a pared down "hero paragraph" and top-level links organized into cards for 3 types of users: new users (New to Flux), existing users (Using Flux), and Developers/Admins (Administration/Development).
The rest of the page is just some useful information if readers make it this far, and links off to other parts of the docs or other projects.
I've iterated a bit to get this into reasonable shape, but haven't fully checked all links for validity so there may be a lot more work here, thus I've set this as a WIP for now. If the readthedocs build works, then we'll be able to see the result via the CI build for more feedback.