Re-platforming Quarkus and Quarkiverse wikis

62 views
Skip to first unread message

Holly Cummins

unread,
Jun 12, 2023, 8:17:08 AM6/12/23
to Quarkus Development mailing list, Stefan Sitani, James Cobb
Hi all, 

At the moment, as well as the main site http://quarkus.io, the Quarkus team maintain two wikis, https://github.com/quarkusio/quarkus/wiki and https://github.com/quarkiverse/quarkiverse/wiki. 

There are a few problems with these wikis*:

  • The Quarkiverse wiki is not indexed by Google. To use information on it, you have to direct-link to it. In other words, it’s where information goes to die.
  • The Quarkus wiki, on the other hand, is indexed by Google. This is good, and makes information on the wiki more accessible … but updating this information is quite hard. Only members of the core Quarkus team can raise PRs.

A wiki where the community can’t find the information is pointless, and a wiki where the community can’t propose changes to information is, basically, not a wiki. 

GitHub recommend using GitHub pages sites if people want their content to be indexed. We can do this, but to make sure we get the design right, we should think first about what problem we’re trying to solve with wikis. What is it that makes this content unsuitable for https://quarkus.io/guides/ and /or https://quarkus.io/blog/? 

I can think of a few reasons. 

  • Lower (perceived) barrier to entry, and more welcoming to the community. 
  • For Quarkiverse in particular, there’s a lot of content, more than we’d maybe want to fit into https://quarkus.io/guides. And the Quarkiverse is a bit distinct from core Quarkus. Most of its documentation is about GitHub processes, rather than technology. Would something like https://quarkus.io/quarkiverse/ be a good home for this?
  • Some stuff just doesn’t fit into Diataxis or a Guides structure? With a wiki, we can be more ad-hoc with our organisation.
  • Promotion conveyor belt. Some teams use a wiki as a place to ‘incubate’ content, which then gets picked up if it’s popular enough. (Knowing what’s popular needs analytics, which we don’t have on the wiki at the moment.)
  • Ephemeral content. Some content is valid at a point-in-time, but then goes stale. 
  • Different audience; a site for people developing Quarkus is not the same as a site for people using it

A related question is ‘how relevant are these needs to the content we have’? If we want the wiki to be a sandbox for content (say), is the current context sandbox-y? Looking at the current content of the main Quarkus wiki, this is what we have. 


I’ve tried to tag the pages with what kind of content they are, and what should be done. The main things where there’s not an obvious “non-wiki” home are Paul's process documentation and Phil’s dev-UI documentation. We also have a few design discussions that were done as wiki pages rather than GitHub issues.

*Technical reasons for the issues

Why isn’t the Quarkiverse wiki indexed? It’s a GitHub policy that wikis are not indexed, I think to prevent malicious changes causing Google to downrank all of GitHub. The Quarkus wiki has an exemption because the Quarkus repo has so many stars.  

Why isn’t it possible to propose changes to the main Quarkus wiki? The repo for the wiki, https://github.com/quarkusio/quarkus.wiki.git, is a sort of semi-secret functional repo that can’t be forked. Because it can’t be forked, most people can’t submit PRs. We worked around this for the Quarkiverse wiki by writing a syncing script which pushes content from a workable wiki to the main wiki. We may have been doing this for the Quarkus wiki at one point, since we have a separate wiki repo, but that repo was abandoned several years ago. 

--
Holly Cummins
Senior Principal Quarkus Software Engineer, Java Champion

Red Hat 


Max Rydahl Andersen

unread,
Jun 15, 2023, 4:23:39 AM6/15/23
to Holly Cummins, Quarkus Development mailing list, Stefan Sitani, James Cobb

On 12 Jun 2023, at 14:17, Holly Cummins wrote:

sorry for delay - long email so took so time to process :)

Hi all,

At the moment, as well as the main site http://quarkus.io, the Quarkus team maintain two wikis, https://github.com/quarkusio/quarkus/wiki and https://github.com/quarkiverse/quarkiverse/wiki.

To be clear, the quarkiverse is deliberately separate from quarkus.io. Their focus on reason to exist is different.

There are a few problems with these wikis*:

The Quarkiverse wiki is not indexed by Google. To use information on it, you have to direct-link to it. In other words, it’s where information goes to die.
The Quarkus wiki, on the other hand, is indexed by Google. This is good, and makes information on the wiki more accessible … but updating this information is quite hard. Only members of the core Quarkus team can raise PRs.

A wiki where the community can’t find the information is pointless, and a wiki where the community can’t propose changes to information is, basically, not a wiki.

yeah, that's why I early on setup the quarkiverse wiki as a real repo. Did the same for quarkus.io but people weren't fan of not being able to use the Edit button directly :)

Idea was that once quarkiverse grew big enough we would start publishing content to quarkiverse.io instead; i.e. wiki.quarkiverse.io and wiki.quarkus.io could be a thing.

GitHub recommend using GitHub pages sites if people want their content to be indexed. We can do this, but to make sure we get the design right, we should think first about what problem we’re trying to solve with wikis. What is it that makes this content unsuitable for https://quarkus.io/guides/ and /or https://quarkus.io/blog/?

Because it is not related to quarkus releases, blogs aren't intended to be updated/living docs and we distinctly want to have quarkiverse hub separate from quarkus.io.

I can think of a few reasons.

Lower (perceived) barrier to entry, and more welcoming to the community.
For Quarkiverse in particular, there’s a lot of content, more than we’d maybe want to fit into https://quarkus.io/guides. And the Quarkiverse is a bit distinct from core Quarkus. Most of its documentation is about GitHub processes, rather than technology. Would something like https://quarkus.io/quarkiverse/ be a good home for this?

no, we have quarkiverse.io and should use it IMO for this.

Some stuff just doesn’t fit into Diataxis or a Guides structure? With a wiki, we can be more ad-hoc with our organisation.

correct.

Promotion conveyor belt. Some teams use a wiki as a place to ‘incubate’ content, which then gets picked up if it’s popular enough. (Knowing what’s popular needs analytics, which we don’t have on the wiki at the moment.)

I don't think we have much of that? Got an example?

Ephemeral content. Some content is valid at a point-in-time, but then goes stale.
Different audience; a site for people developing Quarkus is not the same as a site for people using it

yeah - like I grok why the doc contribute guide is in the guides section but it really isn't where one goes looking - you go look in the related repo.

A related question is ‘how relevant are these needs to the content we have’? If we want the wiki to be a sandbox for content (say), is the current context sandbox-y? Looking at the current content of the main Quarkus wiki, this is what we have.

[main-site, move] Almost all of the Quarkus wiki content is migration guides. That feels like it should perhaps be turned into quarkus.io/migration-guides?

or wiki.quarkus.io/migration - having it in asciidoc and be more structured for reuse and automation (I still have dreams of how revapi could be used to derive/track migration and use to generate migration info) would be a good thing.

[main-site, consolidate-overlaps] https://github.com/quarkusio/quarkus/wiki/Stackoverflow should go into the ‘where to get help’ <https://quarkus.io/support/> sections

Took me a minute to remember what that page is - that is not really for users; it was a page I wrote to help Quarkus devs to know how to follow stackoverflow questions
for Quarkus because stackoverflow is remarkably bad at making that clearly visible.

So its not really for quarkus.io/support but then again - I could see it be a subpage/linked from it as a "If you want to help here is some tips on how to do that"...

[quarkiverse-site, consolidate-overlaps] https://github.com/quarkusio/quarkus/wiki/Adding-extensions-to-the-Quarkus-ecosystem overlaps signficantly with the content in the Quarkus wiki, and should be consolidated

Correct - this has grown over time and was not put into /guides because it is really not part of a specific release as the docs should always be uptodate - not branched/versioned as if there is a difference between Quarkus 2.12 and 3.2 in.

[design-discussion, archive] https://github.com/quarkusio/quarkus/wiki/Bill's-Quarkus-CLI-Scenarios is a technical design for the Quarkus CLI. It feels like it maybe should have been on an issue, and now can be retired.

yes, that should just be an issue or ADR (which we don't use much, but should).

[design-discussion, archive?] https://github.com/quarkusio/quarkus/wiki/Why-Dropping-Java-8 is a design discussion about dropping Java 8

! [developer-oriented-content, new-home] https://github.com/quarkusio/quarkus/wiki/Dev-UI-v2 is documentation about how to extend the new Dev UI. It clearly needs to be somewhere, and maybe it’s an example of the kind of content where the process of writing a guide seemed too formal or heavy?

Yes and it's not really content to be part of a quarkus release. Its where something like "google docs style editing for a asciidoc/wiki site" would really shine.

[repository-content, move] https://github.com/quarkusio/quarkus/wiki/Git-commands-(to-be-added-to-CONTRIBUTING.md) is labelled “to be added to contributing.md”, so can be added there - although again, the question is “why didn’t we put this into contributing.md in the first place? What was the barrier?

Question for Guillaume.

My guess is that it's a very specific thing and if you add many of them the contributing guide becomes massive.
Linked from contributing to wiki seems like a good use of wiki here?

! [developer-oriented-content, new-home] https://github.com/quarkusio/quarkus/wiki/High-Level-Planning-Process is about how we plan Quarkus. This is another example of where GitHub process-related content maybe doesn’t feel like a good for for quarkus.io

yes.

I’ve tried to tag the pages with what kind of content they are, and what should be done. The main things where there’s not an obvious “non-wiki” home are Paul's process documentation and Phil’s dev-UI documentation. We also have a few design discussions that were done as wiki pages rather than GitHub issues.


*Technical reasons for the issues

Why isn’t the Quarkiverse wiki indexed? It’s a GitHub policy <https://github.com/orgs/community/discussions/4992> that wikis are not indexed, I think to prevent malicious changes causing Google to downrank all of GitHub. The Quarkus wiki has an exemption because the Quarkus repo has so many stars.

Why isn’t it possible to propose changes to the main Quarkus wiki? The repo for the wiki, https://github.com/quarkusio/quarkus.wiki.git, is a sort of semi-secret functional repo that can’t be forked. Because it can’t be forked, most people can’t submit PRs. We worked around this for the Quarkiverse wiki by writing a syncing script which pushes content from a workable wiki to the main wiki. We may have been doing this for the Quarkus wiki at one point, since we have a separate wiki repo <https://github.com/quarkusio/quarkus-wiki> , but that repo was abandoned several years ago.

Yes, I set it up but no uptake - I don't recall/remember why I didn't remove it. Probably just marked private to have if it ever became a thing again :)

So, yeah I still think something like a "wiki" is useful - but yes, GitHub's wiki stuff is really not a great place for it.

So ...any suggestions on what we do about it ?

/max

Holly Cummins

unread,
Jun 15, 2023, 8:18:56 AM6/15/23
to Max Rydahl Andersen, Quarkus Development mailing list, Stefan Sitani, James Cobb
TLDR

Design goals/constraints
  • Possible for the community to propose changes 
  • As easy as possible for the community to propose changes, ideally with in-browser editing 
  • Indexed by google
  • Asciidoc and automation support as a first class thing 
  • Clear separation of “how to be in the quarkiverse” content from the main site 
  • Mechanism for reference material which isn’t tied to a particular quarkus release 
I propose the following: 

Quarkus Wiki 

  • Move the Migration guides to the main website. They’re user-oriented content. The main reason to have them on a wiki would be to make them easier to edit. As the current wiki system actually makes it impossible for people in the community to suggest changes to, moving is an easy call. I think this content could be tied to a release, since it’s all about releases … but alternatively we could have a quarkus.io/migration section which lists everything and doesn’t have any release-level hierarchy.
  • For some of the technical design discussion, make an ADR template on GitHub and move them there. (This is a great suggestion, Max.)
  • For some of the process-oriented content, add it into the main repo as a peer to CONTRIBUTING.MD, and link to it from the readme. 
  • Move the content that should be in CONTRIBUTING.MD to that doc.
  • Remove the wiki.

Quarkiverse Wiki 

  • Sort out the hosting/publishing for quarkiverse.io, which at the moment is a registrar holding page.
  • Migrate the current content to this new home as http://quarkiverse.io/docs, and link to it from the “How to write an extension” guide. That will get it indexed. 
  • In the interests of incremental improvement, start with a straightforward migration using GitHub pages hosting and the current markdown content, and work from there
  • Architect to support re-use, asciidoc + markdown, and automation … investigate options for in-browser-editing
  • Remove the wiki and syncing logic, and rename the current wiki repo to reflect the new hosting

Details

Max wrote:

So, yeah I still think something like a "wiki" is useful - but yes, GitHub's wiki stuff is really not a great place for it.

So ...any suggestions on what we do about it ?


So, before I made suggestions, I wanted to understand what problem the current wikis were trying to solve. 

Put another way, why do we want “wiki.quarkiverse.io” instead of “quarkiverse.io” or “docs.quarkiverse.io”? 

sorry for delay - long email so took so time to process :)


Sorry for the long email. :) 

Normally, one might be able to reverse-engineer back from the current solution to the problem, but since the current wikis aren’t actually solving any problems, that’s harder. :) Well, I’m exaggerating slightly - the wikis are linked on from the ‘wiki’ tab of the GitHub repo, which makes it a logical home for contributor-oriented content. (And there’s the theoretical possibility of in-browser-editing, but in practice it’s only for people with special permissions.) I wanted to dig into other motivations for the current structure to make sure I wasn’t missing something. 

Thanks for the responses below, I think that’s helped crisped up the real goals. 

[snip]

I don't think we have much of that? Got an example?

I agree, this isn’t something we’re doing. The list wasn’t “things we’re doing,” it was “what are the reasons people use wikis? which was the one we were thinking of when we set up a wiki?"

Ephemeral content. Some content is valid at a point-in-time, but then goes stale.
Different audience; a site for people developing Quarkus is not the same as a site for people using it

yeah - like I grok why the doc contribute guide is in the guides section but it really isn't where one goes looking - you go look in the related repo.

Agreed, I hadn’t even noticed we had a “contributing” guide until I searched for it. Actually, we have two, a guide just about contributing to docs, and a blog on main-quarkus.

A related question is ‘how relevant are these needs to the content we have’? If we want the wiki to be a sandbox for content (say), is the current context sandbox-y? Looking at the current content of the main Quarkus wiki, this is what we have.

[main-site, move] Almost all of the Quarkus wiki content is migration guides. That feels like it should perhaps be turned into quarkus.io/migration-guides?

or wiki.quarkus.io/migration - having it in asciidoc and be more structured for reuse and automation (I still have dreams of how revapi could be used to derive/track migration and use to generate migration info) would be a good thing.

I agree 100% we should aim for asciidoc, reuse and automation. We write lots of asciidoc for the main quarkus site at the moment, so we can decouple that from the ‘wiki’ label. 

[main-site, consolidate-overlaps] https://github.com/quarkusio/quarkus/wiki/Stackoverflow should go into the ‘where to get help’ <https://quarkus.io/support/> sections

Took me a minute to remember what that page is - that is not really for users; it was a page I wrote to help Quarkus devs to know how to follow stackoverflow questions
for Quarkus because stackoverflow is remarkably bad at making that clearly visible.

So its not really for quarkus.io/support but then again - I could see it be a subpage/linked from it as a "If you want to help here is some tips on how to do that"...


+1

[quarkiverse-site, consolidate-overlaps] https://github.com/quarkusio/quarkus/wiki/Adding-extensions-to-the-Quarkus-ecosystem overlaps signficantly with the content in the Quarkus wiki, and should be consolidated

Correct - this has grown over time and was not put into /guides because it is really not part of a specific release as the docs should always be uptodate - not branched/versioned as if there is a difference between Quarkus 2.12 and 3.2 in.

[design-discussion, archive] https://github.com/quarkusio/quarkus/wiki/Bill's-Quarkus-CLI-Scenarios is a technical design for the Quarkus CLI. It feels like it maybe should have been on an issue, and now can be retired.

yes, that should just be an issue or ADR (which we don't use much, but should).


+1

[design-discussion, archive?] https://github.com/quarkusio/quarkus/wiki/Why-Dropping-Java-8 is a design discussion about dropping Java 8

! [developer-oriented-content, new-home] https://github.com/quarkusio/quarkus/wiki/Dev-UI-v2 is documentation about how to extend the new Dev UI. It clearly needs to be somewhere, and maybe it’s an example of the kind of content where the process of writing a guide seemed too formal or heavy?

Yes and it's not really content to be part of a quarkus release. Its where something like "google docs style editing for a asciidoc/wiki site" would really shine.

[repository-content, move] https://github.com/quarkusio/quarkus/wiki/Git-commands-(to-be-added-to-CONTRIBUTING.md) is labelled “to be added to contributing.md”, so can be added there - although again, the question is “why didn’t we put this into contributing.md in the first place? What was the barrier?

Question for Guillaume.

My guess is that it's a very specific thing and if you add many of them the contributing guide becomes massive.
Linked from contributing to wiki seems like a good use of wiki here?

! [developer-oriented-content, new-home] https://github.com/quarkusio/quarkus/wiki/High-Level-Planning-Process is about how we plan Quarkus. This is another example of where GitHub process-related content maybe doesn’t feel like a good for for quarkus.io

yes.

I’ve tried to tag the pages with what kind of content they are, and what should be done. The main things where there’s not an obvious “non-wiki” home are Paul's process documentation and Phil’s dev-UI documentation. We also have a few design discussions that were done as wiki pages rather than GitHub issues.


*Technical reasons for the issues

Why isn’t the Quarkiverse wiki indexed? It’s a GitHub policy <https://github.com/orgs/community/discussions/4992> that wikis are not indexed, I think to prevent malicious changes causing Google to downrank all of GitHub. The Quarkus wiki has an exemption because the Quarkus repo has so many stars.

Why isn’t it possible to propose changes to the main Quarkus wiki? The repo for the wiki, https://github.com/quarkusio/quarkus.wiki.git, is a sort of semi-secret functional repo that can’t be forked. Because it can’t be forked, most people can’t submit PRs. We worked around this for the Quarkiverse wiki by writing a syncing script which pushes content from a workable wiki to the main wiki. We may have been doing this for the Quarkus wiki at one point, since we have a separate wiki repo <https://github.com/quarkusio/quarkus-wiki> , but that repo was abandoned several years ago.

Yes, I set it up but no uptake - I don't recall/remember why I didn't remove it. Probably just marked private to have if it ever became a thing again :)

I don’t think it was private, because I tried to submit PRs to it. (… since I couldn’t submit PRs for the main wiki, I assumed that wiki was the right mechanism, but …. I was wrong.) Guillaume has now archived it, so that should avoid future confusion. 

George Gastaldi

unread,
Jun 15, 2023, 9:18:02 AM6/15/23
to hcum...@redhat.com, Max Rydahl Andersen, Quarkus Development mailing list, Stefan Sitani, James Cobb
On 15 Jun 2023, at 09:18, Holly Cummins <hcum...@redhat.com> wrote:

Quarkus Wiki 

  • Move the Migration guides to the main website. They’re user-oriented content. The main reason to have them on a wiki would be to make them easier to edit. As the current wiki system actually makes it impossible for people in the community to suggest changes to, moving is an easy call. I think this content could be tied to a release, since it’s all about releases … but alternatively we could have a quarkus.io/migration section which lists everything and doesn’t have any release-level hierarchy.
  • For some of the technical design discussion, make an ADR template on GitHub and move them there. (This is a great suggestion, Max.)
  • For some of the process-oriented content, add it into the main repo as a peer to CONTRIBUTING.MD, and link to it from the readme. 
  • Move the content that should be in CONTRIBUTING.MD to that doc.
  • Remove the wiki.
+1, sounds like a good plan


Quarkiverse Wiki 

  • Sort out the hosting/publishing for quarkiverse.io, which at the moment is a registrar holding page.
That involves opening tickets to IT. I can help you with that, as I have already done that several times ;)  
  • Migrate the current content to this new home as http://quarkiverse.io/docs, and link to it from the “How to write an extension” guide. That will get it indexed.
+1, but because some publications (books) refer to the current Quarkiverse URL we need to redirect them somehow to avoid broken links. 

Reply all
Reply to author
Forward
0 new messages