Could I make a suggestion to improve onboarding experience for Docs contributions in light of the new 3.0 site?
Issue
There are several Docs links to the documentation landing page scattered throughout the new 3.0 site. Contributors find it difficult to find ‘how to get involved’ because Docs team page, README, wiki have discrepancies in joining instructions.
Expected result
Contributors see clear signpost on the landing page, so they quickly find tasks that suit their interest and expertise, regardless of long-term time commitments.
Bypass or remove intermittent steps (microsite, SIGs, other communication channels) before contributors get to work
More commits and PR review for collaboration
Raise more awareness on Documentation contributions
Solution
Putting call-to-action (CTA) links on the documentation landing page for role-based ‘Join us’ messaging
QuickDocs has 87 pages to maintain and needs expert technical review on a regular basis. We need subject matter experts to examine the content for technical accuracy and up-to-dateness.
Improve user experience
Note: This page requires a major update by UX specialists. The vast majority of issue/MR in GitLab Docs repo comes from UX improvement, mass update (CSS, AsciiDoc attributes), and automation (CI script).
I agree that information discovery about contributing is difficult from the current Docs homepage. It can take many clicks to find someone is looking for, and a more generic entry-point would be easier than exploring each team in individual detail.
I see the changes you propose here as more specific to Fedora Docs. Is this your intention, or do you think something more general for all of the Fedora community would be better?
Since I entered my role at Red Hat, I quietly established the below docs site and have added things there bit by bit. I wasn’t sure if I wanted to keep it or not yet. Perhaps this could be a chance to figure out a bigger purpose for the site:
Yes, what I posted here is Docs specific (Docs homepage and user documentation like QuickDocs) request to make ‘how to contribute to Docs’ visible in the new website. I’ve broken CTA down to three types of contributions.
I took the idea from ‘email subscription’.
Back to your observation on CommArch documentation page,
I slowly realized the overarching function and team in the Fedora project thanks to you. CTA (Call to action) approach could be too much task-oriented, but it measures effectiveness of our efforts and user journey on our website. Just nitpick on the participation process of CommArch is “Phase 0 - bootstrap” sounds loftier than necessary.
I reckon almost each project team has its tweaks on joining instructions (or onboarding). Sometimes, I got lost in going through all kinds of joining process, request to access or special permissions (commits and so on). To me, a simple joining process appeals to me. That’s why I joined Magazine team within two days after installing my first Linux desktop. CTA (how to contribute to Magazine) was right in front of the home page when I opened up Firefox.
Do you think content about the Fedora community, its history, and stories/milestones is useful content? Why or why not?
I still have to figure out that whole onboarding path thing. I fell back on it because one pathway feels very rigid for what someone can do in Fedora. Maybe there need to be different contribution pathways that can go in different directions.
I think this will be a separate topic from here, but I’ll keep this one in mind with the Community Ops discussion happening over here:
Yes, it is useful. Fedora Join sends out the links about introduction to Fedora projects. It helps prospective contributors (it did to me as well) to explore the community and get to know people and pathways. They may not read all of them, but find a right task that suits their interest and expertise or opportunity to learn by doing.
Yeah, I agree, we need to improve and strengthen our onboarding efforts. And CTAs may be a good way.
Then my first thought was: where to put it on the Docs home page? On the one hand, the design is somewhat ancient nowadays. On the other hand, it allows a large amount of information to be presented clearly. But it is a bit inflexible, and offers hardly any possibilities to include CTAs.
Second thought was, then, wouldn’t it be better to include CTAs systematically on the editions and spins pages? There, the design also offers better options. You could do it similar to Fedora Magazine.
In any case, we should think about it. This is an urgent topic.
Join SIG on the new contributor menu: Join SIG onboards prospective contributors in Welcome To Fedora, which gives them time to introduce them to the community and get to know each other.
These paths are sign-posted clearly. I’m not suggesting to unify these well-known paths. I think we need to do “how to join” messaging with How to join Fedora resources on the right location in the new website. This is consistency we need.
Hi folks, following discussion here between April and May, waiting for feedback on ‘how to join’ message for Docs contributors, and the latest Docs meeting, here is the revised proposal.
Where to put role-based ‘Join us’ CTA?
Before: Documentation landing page
After: Quick Docs home page
I believe in do-ocracy way of doing things. If you wanna achieve anything, make sure the community knows about it. If there are no complaints, soldier on. Don’t dither or over-think. If there are objections, sincerely address them. But don’t let it hang indefinitely. ↩︎
Before I go ahead with this, could anyone advise me if there is a way to insert a banner and text into Quick Docs? Would the new CMS support Quick Docs?
I mean netlfy CMS, hoping to create CTA using graphical interface. I wasn’t sure of mechanics of how to add a banner and text into Quick Docs.
So I gather one needs to add HTML and CSS into Quick Docs. Well, this is not in my skill set, so my question is - which GitLab repo do I need to make a request to?
If you want to add something to the Quick Doc homepage, then it’s on the Quick Docs repository, and more precisely here for the homepage.
No HTML or CSS needed, you can just use plain asciidoc.
The Fedora Doc UI repository is only for documentation site-wide modification (i.e. that impact the entire docs.fedoraproject.org website, not just quick docs).
In the very most cases, the TOC does not fill up the space. So we could dynamically add a CTA Logo, box or something else.
And doesn’t have Antora the option to pass through directly html/CSS code? I saw some quite adventurous pages.
And we want to start CTA with Quick Docs and gather some experiences with it. I think sooner or later we would like to introduce this on other pages as well.
I must confess CTA in marketing isn’t about goals/priorities, but about why we invite new visitors to take a journey with us. In eStore, “Buy now” is a clear call to action.
How can we turn this into FOSS contributions?
In the Fedora home page, the most obvious and clear CTA is “Get Fedora” and “Download now”.
Join SIG and contributor guides are a few clicks away. However, these are not obvious to new visitors that we want them to contribute (how and where).
What could be CTA that should be displayed on top right so people can click it and do something.
For an example,
“Register” button (Fedora Account): Register with the Fedora Account
– What benefits you will get from it?
Join weekly meeting of your choice of work group or SIG
Ask for a mentor
The most vibrant workgroups/SIGs have a history of building mentorship, support of various communication methods and face to face engagement (local or regional)
Start contributing
– Get recognition by peers and enhance personal development; Types of contributions, recent work completed
– Increase professional network
Anything more than four steps will put people off.
In general, we need to bring “more action” and “more liveliness” to the homepage. At present, the page remains unchanged until the next release. And then it will only change marginally. From a UX perspective, the page quickly becomes “well known”, “you know” what to expect and don’t really look at it anymore. This means that the site is no longer attractive enough to inspire people to do something new, especially not to become active and join in.
A first, albeit small, step would be to make the buttons in the header more “active”, “Get Fedora” is a good example. Instead of a somewhat pale “Contributors”, perhaps a “Join the Makers” or „Add Your ideas here. It should be more of an invitation to join in. Similar with “Connections”, maybe something like “Get to know the Community” (it’s too long, but something more inviting).
We should also consider whether we want to stick with the wording “Learn More”. It sounds a bit patronizing and, above all, passive. Something more active and more “on an equal footing” would be something like “Explore Details”.
And we need more indication that we are “living” and not just are around. Maybe on the opposite side of “Public Good” the next 1-2 ongoing activities: next team meeting, next social event, ongoing discussion about next flock, something like that. We have to arouse curiosity and “entice” people to “click for a quick look” and see what’s on.
