How to PASSIVELY let users know THAT and WHAT they can contribute?

As suggested and discussed with @hankuoffroad some time ago, I open a new topic to consolidate and discuss the possibilities/approaches to “capture” people when and where they interact with the Docs for telling them THAT they can contribute (we should not presume that any user on Docs pages already knows) but also WHY, WHEN, WHERE and HOW they can contribute OR reach us (I derive from Sampson’s points [1] [2] that how/when/where/how reaching us could be an issue as well, which can limit contribution at Docs but also the Docs value for them): so discuss the issues from a new perspective in a dedicated manner, as targeted in the Matrix discussions.

Users interact with Docs on our pages, which does not automatically lead them to actively search and read “team pages” (or scroll down to the bottom of a page or check out the meaning of graphical buttons ONCE they have what they wanted from Docs, such as a technical information). What we have on our pages so far makes it necessary for users to become active to seek information about Docs contributions/organization, which means they have already some incentives and intentions to get in touch with Docs and that they know they can (thus, the above questions need to be already answered to some extent in advance). Therefore, the passive part is important: information they receive passively when on any Docs page (where and when they get value from Docs) immediately just by opening a Docs page (e.g., this can already exclude graphical “bug” buttons that most users link to software engineering so that they do not even check what the button means).

We have to keep in mind that people tend to visit Docs to get technical information, not to contribute (and their behavior on Docs pages is tailored to corresponding incentives/demand). We have to add passive incentives they immediately perceive to facilitate knowledge of the latter so that people at least know THAT they can contribute with some incentives of HOW/WHAT, and then they can decide on themselves if they want.

Some potential triggers/incentives from what could be presented (and when) on Docs pages passively (may it be buttons with text or distinctly-easy-to-understand graphics, or something else that “answers” questions passively → “passively” in terms of the users being not needed to become active by moving pointer over graphics or so, because they will not do that without having a reason in advance):

  • “Page update necessary?”, which leads to …
    • “… Let us know in discourse!” → forward to automatically open a topic on discourse - we just had this one case :slight_smile:
    • “… Let us know in Matrix” → forward to Docs channel
  • “You prefer git? Change it yourself or just leave us a ticket” → git ticket forwarding OR git repository forwarding"
  • “Docs seek people” → forward to a very short page with just a few bullet points of WHAT could be done (types of contributions, regular and casual, with responsibility and without), some links to team pages (WHAT we are: structured, organized, …), and HOW to reach us
  • “Some tasks unclear or don’t work?”, which leads to …
    • " …Open a ticket on ask.fedora!" → automatically forward to open a ticket with #docs tag on ask.fedora. → we might ask the wider community first if the would consider that, I think it is in scope, but it is a little probabilistic
    • " … ask us on Matrix" → as above
  • “Are you seeking initial understanding of git(lab) while contributing by instructions?” Hanku’s approach to the GitLab guide if we keep a GitLab guide online → offer people the possibility to gather git experience/understanding through Docs (@hankuoffroad , correct me if I misinterpreted your GitLab approach!) ¹

→ login-less alternatives like hackMD or Etherpad were put forward by @hankuoffroad to keep the entry barrier low. This might be also a solution for “report an issue” (beyond the points above, see also ticket #23 as incentive).

The above “buttons” in sum have obviously too much text to be a final, but they are an incentives to rationalize the issue and foster discussions from that perspective. So don’t take it too literally :wink:

¹ Related to the button for the potentially new GitLab guide approach suggested by @hankuoffroad (I think we agree that if there is any remaining approach that gives this guide a role in the current circumstances, it is his suggested one): is there an audience for a guide that helps people to get deeper into git through Docs contributions? (I think yes, but …) Will such an audience formulate search queries (or have surfing behavior) that make them end up at Docs pages or end up there by other means with their goal? If not, can we trigger that somehow? Alternatively, can we passively link “Docs” + “make git experience/deepen git knowledge” at those who are on Docs pages for other reasons but who have general interest in developing their git knowledge?. The git experienced audience likely needs only GItLab Docs, and the audience that does not want to engage in git-specific actions cannot be served in the new GitLab UI. So can we determine an audience in between that the guide can serve?

Of course we have to also ensure that whatever we do on Docs pages, we have to avoid that the focus is shifted from the content to our organization/contributions.

@hankuoffroad feel free to add your remaining points and approaches (I am not sure if I could capture them sufficiently). I think you had more.

Let’s consolidate issues, approaches, discussions around this type of questioning/reasoning here to get some order around it. This topic is not for immediate changes or so but something to contribute to identifying and evaluating what to do and where to develop on the long term in the related issues…

Holy mackerel, that’s a lot to ask!

I have no energy to debate on things I shared off the cuff between you and me. It is unfair for my name to be quoted for that. You ask hard questions.

Share your thoughts and offer your help when you are around.

I appreciate the idea of passively let users know … A good place the that on docs pages could be the right margin at the bottom, may a box at the bottom of the viewport.

Problem is, it would be quite a work to modify the CSS/html of the page. And before we have to prepare the tools and the target page(s). Maybe we could try to start with a smaller “box” with a short text and a pointer to the buttons at the top and one additional link. Quick Docs would be a good test field. Again, before that we need to update our contributor guides.