Add flux docs assessment #89
Conversation
celestehorgan
force-pushed
the
add-flux-assessment
branch
from
892d31e
to
b39c756
Compare
|
Upon further reflection I'm going to revisit the final conclusions section of this one tomorrow/later today - I think there's more to say and I just got a bit lazy/tired. |
|
👋 Looping in a few Flux maintainers. cc @darkowlzz @hiddeco @kingdonb @makkes @phillebaba @relu @scottrigby @squaremo @stefanprodan |
|
Thanks so much for the review - I just found the PR today. I'll bring it up with the Flux maintainers and we'll review this together. Please let us know if there any next steps, if we should come to one of your next meetings, or if there's a way for us to benefit some more from your experience! This is really great! 🏆 ❤️ |
| - Items under the **Project** top level navigation section. At a glance I couldn't figure out how these were being pulled in via (I assume) the [Community repository](https://github.com/fluxcd/community), meaning they suffer either from a lack of documentation or unclear automation. | ||
|
|
||
| - Documentation versioning: Flux's documentation is not versioned but the tool itself has been versioned. | ||
| - This leaves existing users of v1 who haven't upgraded in a difficult position: if they need to troubleshoot an issue, they can't access v1 documentation. |
There was a problem hiding this comment.
While this is apparently not transparent enough given you did not find it, the legacy docs which were homed at https://docs.fluxcd.io are still there, and we have preserved all existing hyperlinks (hopefully). We do not draw attention to them and in fact we've done everything we can to downplay their SEO, which also has the unfortunate side-effect that they are not searchable anymore outside of the site.
I was pretty sure we had rendered them completely un-searchable because of the difficulty of maintaining two parallel search engines for the same domain. But I just checked, and users who find https://docs.fluxcd.io or https://fluxcd.io/legacy/flux/ that it redirects to, can in fact search Flux v1 docs, and they appear to be every bit as functionally accessible as they ever were (when you're able to find them at all.)
Hope this helps! Thanks!
There was a problem hiding this comment.
I had a review holding in mind a question, "how are users (that inherit a Flux v1 installation, lets say) supposed to find the legacy docs" and it looks like there's now only one straightforward way, on the front page, about 11 pages of content in (or about 80% of the way down the scroll bar.) I opened an issue so we can address this 👍 fluxcd/website#689
Closes #59 by adding the Flux docs assessment
cc @alisondy - Are you still a maintainer for Flux? if not, who would you like to pass this review on to?