Documentation landing page CTA (Call to action) - Your feedback is important

Hi folks,

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
  • Link to each UI text for CTA and link

Write a new how-to-guide or tutorial

Do technical review

https://pagure.io/fedora-docs/quick-docs/issues

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).

Issue ticket here for your feedback

New Docs logo

fedora-docs

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:

2 Likes

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.

2 Likes

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.

1 Like

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.

There are three well-trodden paths to join Fedora project sub-groups or SIGs;

joining

  • 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.

  • Role-based CTA: https://fedoramagazine.org/

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.

  1. Where to put role-based ‘Join us’ CTA?
    Before: Documentation landing page
    After: Quick Docs home page

  2. What roles Docs wants to nurture and develop?

  1. Rationale for messaging: Learn by doing, develop your skills and get hands on with latest Docs tool set.

Next step

Please let Docs team know on this thread if you have any suggestions to the proposal or objections.

Share your feedback by 7 July 2023. If we are all in agreement by then, I will open a merge request for a change.

Thanks!

[1]


  1. 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. ↩︎

2 Likes

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?

+1 to adding a banner/notice to the Quick Docs site.

I’m not sure what you mean by this, but my first thought would be no, since they are two different tools/systems (i.e. Antora versus VueJS).

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?

Ah, sorry! I am not familiar with a Fedora Docs workflow using Netlify. Is that something we have already now?

Most likely, it needs to be included somehow here:

I am not familiar with a Fedora Docs workflow using Netlify. Is that something we have already now?

I don’t know it, either. I logged into Netlify (Decap) to get acquainted with user interface, I searched for Quick Docs, but not found.

Ah okay, thanks for pointing me to the right repo’ Fedora Doc UI’ using Antora.

The Netlify CMS is only for the fedoraproject-v3 website (https://fedoraproject.org), nothing else.

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).

Thanks for your help. Using index.adoc, is it possible to use empty space on the right of Quick Docs home page?

You can’t. This space is reserved for the table of content.

OK, CTA text is added at the end of main body of QD index page. Checked it with build/preview script and committed.

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.

marketing-team commops-team

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.

Very good to come back to this topic!

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.

1 Like