Search is the leading problem, but I think we can probably clean up the navigation quite a bit. It just kind of ... grew this way.
1. Remove F34 and Rawhide bubbles. Let's just feature the latest. If we want older release docs to be more prominent, we can style the version-changer more prominently.
2. Definitely remove links to the really old docs, as previously discussed.
3. Having EPEL on the front page separately still seems good, considering the user base and that EPEL is one of the most popular queries leading to the site.
4. I'm unsure about front page bubbles, but -- I think we should put all of the Edition / spin documentation into one three-level hierarchy instead of lots of two-level ones.
5. I still kind of like "Fedora Project" as a little mini-site, but maybe _all_ of the rest of Fedora Council, Engineering Teams, Mindshare Teams, D&I, PgMT should be put into one?
6. Not sure where stuff like Gaming should go.
7. Packaging guidelines and to-be-added Legal... same.
8. Outreachy docs should be removed, since they're not on the docs site.
9. GCP should be removed because we're not doing that anymore.
On Wed, Dec 8, 2021 at 9:50 PM Matthew Miller mattdm@fedoraproject.org wrote:
Search is the leading problem, but I think we can probably clean up the navigation quite a bit. It just kind of ... grew this way.
It's definitely time to tend the garden a bit.
- Remove F34 and Rawhide bubbles. Let's just feature the latest. If we want older release docs to be more prominent, we can style the version-changer more prominently.
I disagree. A lot of users don't upgrade right away, so making the docs harder to find is a disservice. If you want to get rid of something, Rawhide seems like the better candidate as many fewer people actually use it.
- I'm unsure about front page bubbles, but -- I think we should put all of the Edition / spin documentation into one three-level hierarchy instead of lots of two-level ones.
I'm not sure what you mean by that. Can you elaborate?
- I still kind of like "Fedora Project" as a little mini-site, but maybe _all_ of the rest of Fedora Council, Engineering Teams, Mindshare Teams, D&I, PgMT should be put into one?
I think I see what you're saying, and that makes sense. Basically a unified listing of teams? If that's what you mean, then I'm on board. If you don't already know about Fedora's org structure, then the docs make it harder to find what you're looking for.
- Not sure where stuff like Gaming should go.
Are we talking about using Games or participating in the Games SIG?
- Packaging guidelines and to-be-added Legal... same.
Probably in a grouping under an Engineering Teams heading for packaging guidelines. Legal...is more expansive. Maybe with broader things like Council and DEI?
- Outreachy docs should be removed, since they're not on the docs site.
Why does it matter if it's on the docs site? It's still documentation. The docs page should be about the content, not the tooling. Now if you want to make the case that we should remove it because it points to a 2017 wiki page, that's another matter entirely.
- GCP should be removed because we're not doing that anymore.
Go for it!
On Thu, Dec 09, 2021 at 09:15:46AM -0500, Ben Cotton wrote:
I disagree. A lot of users don't upgrade right away, so making the docs harder to find is a disservice. If you want to get rid of something, Rawhide seems like the better candidate as many fewer people actually use it.
I don't think it'd actually be harder. Look at Python documentation — the top level links all go to https://docs.python.org/3/, which defaults to "latest", but you can choose earlier versions from the dropdown. We have that same thing with Antora, but two entry points.
Also though: that versioned documentation contains three things:
1. Release notes — clearly useful as versioned)
2. The installation guide — theoretically, the installer is tied to releases, but... it hasn't changed significantly in _years_ and new changes are not even prototyped. Do we really need a versioned ... version of this? Maybe Install Guide is its own thing at the top level.
3. System Administrator's Guide — actually, I think this should be entirely decomposed and put into Quick Docs on a topic-by-topic basis.
- I'm unsure about front page bubbles, but -- I think we should put all of the Edition / spin documentation into one three-level hierarchy instead of lots of two-level ones.
I'm not sure what you mean by that. Can you elaborate?
Yes. Right now, once you click on https://docs.fedoraproject.org/en-US/fedora-server/, you're in that space, and https://docs.fedoraproject.org/en-US/iot/ is another, each with unique left menus. What if we put them all into one unified menu, with the edition names as top-level menu items on the left menu?
- I still kind of like "Fedora Project" as a little mini-site, but maybe _all_ of the rest of Fedora Council, Engineering Teams, Mindshare Teams, D&I, PgMT should be put into one?
I think I see what you're saying, and that makes sense. Basically a unified listing of teams? If that's what you mean, then I'm on board. If you don't already know about Fedora's org structure, then the docs make it harder to find what you're looking for.
Yes, exactly.
- Not sure where stuff like Gaming should go.
Are we talking about using Games or participating in the Games SIG?
I guess it is the later. But where would user documentation produced by that team go?
- Packaging guidelines and to-be-added Legal... same.
Probably in a grouping under an Engineering Teams heading for packaging guidelines. Legal...is more expansive. Maybe with broader things like Council and DEI?
Sure. :)
- Outreachy docs should be removed, since they're not on the docs site.
Why does it matter if it's on the docs site? It's still documentation.
Because we're steering people back into the wiki, perpetuating the confusion of our current "where are the docs" story.
The docs page should be about the content, not the tooling. Now if you want to make the case that we should remove it because it points to a 2017 wiki page, that's another matter entirely.
Or to put it another way: I don't think the docs.fpo front page should serve as an index to the wiki, even if that part of the wiki is kept up to date.
On Thu, Dec 9, 2021 at 11:52 AM Matthew Miller mattdm@fedoraproject.org wrote:
I don't think it'd actually be harder. Look at Python documentation — the top level links all go to https://docs.python.org/3/, which defaults to "latest", but you can choose earlier versions from the dropdown. We have that same thing with Antora, but two entry points.
Sure. This topic isn't worth a battle royale for me, but I do think it would represent a regression in how we present our documentation, even though the docs are still there and findable.
Also though: that versioned documentation contains three things:
This is a digression, but I agree with all of it.
Yes. Right now, once you click on https://docs.fedoraproject.org/en-US/fedora-server/, you're in that space, and https://docs.fedoraproject.org/en-US/iot/ is another, each with unique left menus. What if we put them all into one unified menu, with the edition names as top-level menu items on the left menu?
That would represent a pretty significant paradigm shift. We might be able to get all of the docs to pull nav.adoc from an external repo, but that would break local preview builds. Otherwise, we'd need to combine all of those into a single repo, which presents its own set of challenges.
The other approach would be to reproduce all of the nav in each module's nav.adoc. But this would require being kept in sync manually. That content would be relatively static, so it wouldn't drift too often, but that also means we'd probably forget about it when a new change is made.
- Not sure where stuff like Gaming should go.
Are we talking about using Games or participating in the Games SIG?
I guess it is the later. But where would user documentation produced by that team go?
For the latter, it would be under Engineering Teams. For the former, when it exists, it would go under Quick Docs or release-specific docs, I'd say.
- Outreachy docs should be removed, since they're not on the docs site.
Why does it matter if it's on the docs site? It's still documentation.
Because we're steering people back into the wiki, perpetuating the confusion of our current "where are the docs" story.
Or to put it another way: I don't think the docs.fpo front page should serve as an index to the wiki, even if that part of the wiki is kept up to date.
I agree with the fact that "where are the docs" is confusing. But using docs.fp.o to point to things that are still in the wiki for whatever reason makes it less confusing. The story is "go to docs.fp.o and follow the link you want". If that stays on docs or sends folks to the wiki or readthedocs or whatever other platform, that's okay. The point is that docs.fp.o becomes _the_ front page of our documentation.
On Thu, Dec 09, 2021 at 12:13:11PM -0500, Ben Cotton wrote:
I don't think it'd actually be harder. Look at Python documentation — the top level links all go to https://docs.python.org/3/, which defaults to "latest", but you can choose earlier versions from the dropdown. We have that same thing with Antora, but two entry points.
Sure. This topic isn't worth a battle royale for me, but I do think it would represent a regression in how we present our documentation, even though the docs are still there and findable.
Also though: that versioned documentation contains three things:>
This is a digression, but I agree with all of it.
Ohhhh, let me expand my thought then, because it wasn't meant to be a digression. Having top-level big blocks for versioned documentation makes sense if, when you go there, there's a whole bookshelf.
But we really only have ONE versioned document, the release notes. It seems better to make the top level thing just be "Release Notes", and to make the version more prominent once you go there.
Yes. Right now, once you click on https://docs.fedoraproject.org/en-US/fedora-server/, you're in that space, and https://docs.fedoraproject.org/en-US/iot/ is another, each with unique left menus. What if we put them all into one unified menu, with the edition names as top-level menu items on the left menu?
That would represent a pretty significant paradigm shift. We might be able to get all of the docs to pull nav.adoc from an external repo, but that would break local preview builds. Otherwise, we'd need to combine all of those into a single repo, which presents its own set of challenges.
The other approach would be to reproduce all of the nav in each module's nav.adoc. But this would require being kept in sync manually. That content would be relatively static, so it wouldn't drift too often, but that also means we'd probably forget about it when a new change is made.
Ohhhhh, no, those sound like terrible options. But I think there's a better way than either one? https://docs.antora.org/antora/2.3/navigation/include-lists/
- Not sure where stuff like Gaming should go.
Are we talking about using Games or participating in the Games SIG?
I guess it is the later. But where would user documentation produced by that team go?
For the latter, it would be under Engineering Teams. For the former, when it exists, it would go under Quick Docs or release-specific docs, I'd say.
We might need to rethink Quick Docs if we keep throwing everything in there. :)
Or to put it another way: I don't think the docs.fpo front page should serve as an index to the wiki, even if that part of the wiki is kept up to date.
I agree with the fact that "where are the docs" is confusing. But using docs.fp.o to point to things that are still in the wiki for whatever reason makes it less confusing. The story is "go to docs.fp.o and follow the link you want". If that stays on docs or sends folks to the wiki or readthedocs or whatever other platform, that's okay. The point is that docs.fp.o becomes _the_ front page of our documentation.
Hmmm. I might be convincible on this (even though M-W doesn't think that's word).
On Thu, Dec 09, 2021 at 12:13:11PM -0500, Ben Cotton wrote:
We might need to rethink Quick Docs if we keep throwing everything in there. :)
welllll, i did have a non-antora solution for quickdocs -- it has search, l10n, and asciidoc support:
note that the demo there i had to pull down because google was finding that insread of the real quickdocs
cheers, ryanlerch
On Thu, Dec 9, 2021 at 11:52 AM Matthew Miller <mattdm(a)fedoraproject.org> wrote:
Sure. This topic isn't worth a battle royale for me, but I do think it would represent a regression in how we present our documentation, even though the docs are still there and findable.
This is a digression, but I agree with all of it.
That would represent a pretty significant paradigm shift. We might be able to get all of the docs to pull nav.adoc from an external repo, but that would break local preview builds. Otherwise, we'd need to combine all of those into a single repo, which presents its own set of challenges.
The other approach would be to reproduce all of the nav in each module's nav.adoc. But this would require being kept in sync manually. That content would be relatively static, so it wouldn't drift too often, but that also means we'd probably forget about it when a new change is made.
For the latter, it would be under Engineering Teams. For the former, when it exists, it would go under Quick Docs or release-specific docs, I'd say.
I agree with the fact that "where are the docs" is confusing. But using docs.fp.o to point to things that are still in the wiki for whatever reason makes it less confusing. The story is "go to docs.fp.o and follow the link you want". If that stays on docs or sends folks to the wiki or readthedocs or whatever other platform, that's okay. The point is that docs.fp.o becomes _the_ front page of our documentation.
Also, i am happy to help out implementing some of these ideas (also the ones from the other thread too).
He just need to break this down into what we acutally want done, and ill do it.
is there a central ticket queue to track overarching stuff like this?
cheers, ryanlerch
On Thu, Dec 9, 2021 at 6:28 PM Matthew Miller mattdm@fedoraproject.org wrote:
Ohhhh, let me expand my thought then, because it wasn't meant to be a digression. Having top-level big blocks for versioned documentation makes sense if, when you go there, there's a whole bookshelf.
But we really only have ONE versioned document, the release notes. It seems better to make the top level thing just be "Release Notes", and to make the version more prominent once you go there.
Okay, that makes sense. I'd like to have more versioned docs, but there are a lot of things that I'd like. :-)
Ohhhhh, no, those sound like terrible options. But I think there's a better way than either one? https://docs.antora.org/antora/2.3/navigation/include-lists/
No, that's the "pull nav.adoc from an external repo" I was talking about. It will break local preview builds. Well, _break_ isn't the right word, because the builds will happen. But the include won't happen without building the entire site.
We might need to rethink Quick Docs if we keep throwing everything in there.
No argument here. More than anything other improvement we're discussing, some intentional curation of the docs would improve the situation. The difficulty is that good organization is a specialized skill that we don't, AFAIK, have. It also tends to get out of date pretty quickly. Alas.
On Fri, Dec 10, 2021 at 03:45:10AM -0000, Ryan Lerch wrote:
welllll, i did have a non-antora solution for quickdocs -- it has search, l10n, and asciidoc support: https://pagure.io/docs-fedora note that the demo there i had to pull down because google was finding that insread of the real quickdocs
I'm not completely opposed to going back to that, especially if we can do that with minimal disruption to groups who have worked on the current docs.
I don't think the hoped-for advantages of Antora have really worked out. However, I _am_ a little worried about adding another system that's Fedora-specific... Antora at least has an upstream.
Also, we'd probably need to do a bunch of redirects to avoid dead links, which we _can_ do but we should make sure we're sure so we don't end up doing it again in two years.
On Tue, Dec 14, 2021 at 8:46 AM Matthew Miller mattdm@fedoraproject.org wrote:
On Fri, Dec 10, 2021 at 03:45:10AM -0000, Ryan Lerch wrote:
welllll, i did have a non-antora solution for quickdocs -- it has search, l10n, and asciidoc support: https://pagure.io/docs-fedora note that the demo there i had to pull down because google was finding that insread of the real quickdocs
I'm not completely opposed to going back to that, especially if we can do that with minimal disruption to groups who have worked on the current docs.
I don't think the hoped-for advantages of Antora have really worked out. However, I _am_ a little worried about adding another system that's Fedora-specific... Antora at least has an upstream.
Also, we'd probably need to do a bunch of redirects to avoid dead links, which we _can_ do but we should make sure we're sure so we don't end up doing it again in two years.
Yeash sorry, this was a little tongue-in-cheek comment. Having two toolchains (one designed for docs, and one being a pelican theme) is probably a maintenance nightmare that i cant commit to anyway.
That being said -- not sure Antora the way we are currently using it is meeting our needs either.
cheers, ryanlerch
-- Matthew Miller mattdm@fedoraproject.org Fedora Project Leader _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
On Tue, Dec 14, 2021 at 09:26:06AM +1000, Ryan Lerch wrote:
Yeash sorry, this was a little tongue-in-cheek comment. Having two toolchains (one designed for docs, and one being a pelican theme) is probably a maintenance nightmare that i cant commit to anyway.
That being said -- not sure Antora the way we are currently using it is meeting our needs either.
Are there any other options worth exploring?
I mean, we could always use https://meta.discourse.org/t/discourse-docs-documentation-management-plugin/...
:)
(I am not actually suggesting this. It has search, but not a great search UI, and in general I don't think it'd support everything we really need. Not to mention it'd mean switching to Markdown, which I actually don't think would be the end of the world, but we've got a lot of Sunk Cost there.)
Matthew Miller mattdm@fedoraproject.org wrote: ...
That being said -- not sure Antora the way we are currently using it is meeting our needs either.
Are there any other options worth exploring?
I have experience of Sphinx, and I've tested mkdocs and docsify relatively recently. I'm also aware of Gitbook, mdbook, and some custom solutions I've seen, including our own developer portal.
Selecting a tool obviously depends on what the goals and requirements are, and it would be interesting to know why Antora was selected previously. There are some things that I think we obviously want, like search and ease of contribution. But there are also some more open questions:
- Style of navigation and site organisation. Book-like docs tools are fairly common (see Sphinx, Gitbook, mkbook, etc). However, if we want docs with a more granular structure, we're likely looking at some kind of CMS or a custom solution. - Translations - always a thorny question. They often sound great in principle but are harder to do in practice - you need the translations to have a high level of coverage and to be actively maintained in order to be useful. - What kind of resources do we have to style and maintain the site? (I am assuming we want something that isn't a vast amount of work to look good, and to keep looking good?) - One site or many? And how to link them together.
But for me, the biggest question is how to create a platform that fosters organic community participation. Honestly, I'm not sure what the answer is there. I see some successes in more tightly defined projects, but for large scale projects like Fedora it is more challenging.
I mean, we could always use https://meta.discourse.org/t/discourse-docs-documentation-management-plugin/...
The main question I'd ask there is the whether contributors would update posts they didn't originally author.
... it'd mean switching to Markdown, which I actually don't think would be the end of the world, but we've got a lot of Sunk Cost there.)
I'd be interested to know what are those Sunk Costs are...
Allan
docs@lists.stg.fedoraproject.org
-
Allan Day -
Ben Cotton -
Matthew Miller -
Ryan Lerch