Fixing Docs badges

I think it’s time to fix and update the old badge system - it’s been out of order for years now, we have 3 sets of badges that exist but they’re pointing at the wrong thing, so they’re not being awarded.

The current badge sets are:

  • Wordsmith (overall commits to docs)
  • Beat Writer (commits to Release Notes)
  • Cookbook (commits to the Cookbook, which was essentially a predecessor to Quick Docs)

Here’s the situation for each of them:

Beat Writer

https://badges.fedoraproject.org/badge/working-a-beat-beat-writer-i

Easy to fix, just point the yaml at the current Release Notes gitlab repo.

The name is a bit outdated - a long, long time ago, individual release notes were referred to as “beats” and we would collect them on a Wiki page (for ease of use - so people wouldn’t have to deal with git), and before release, the docs project lead would grab them from the wiki, mark them up (in DocBook back then), and commit them into the relnotes repo. I think the name is kinda cute and I’m inclined to keep it just for the history behind it, but we could also change it to something like “Release Notes Writer”. What do you think?

Regarding levels - there are four of them, and thresholds are 1, 5, 10, and 25 “beats”; each of them is named “Workin’ a Beat”. We might want to increase the thresholds, because I can do 25 in a single release and that’s no fun. How about bumping it up to 5 levels, and doing maybe 1 (to encourage completely new people), 5, 50, 250, and 1000? Any other ideas?

Wordsmith

https://badges.fedoraproject.org/badge/novice-wordsmith-i

This one should be tracking overall docs contributions (although it never really did that). It was originally set up in a time where we only had user docs (Install Guide, Sysadmin Guide, Release Notes…) on docs.fp.o, and now we have a bunch of project docs as well. So one question is - do we want to track everything that’s published on docs.fp.o, or just user docs? My opinion is to track everything, because e.g. Packaging Guidelines or FESCo docs are still docs, and some user docs like Quick Docs and Relnotes have their own badges anyway, but that will require us to, ideally, remember to update the rules every time we add a new repo.

Also, do we want this to track everything, or everything EXCEPT Release Notes and Quick Docs since those will have separate badges? On one hand, RNs and QDs still fall under the umbrella of “docs”, but on the other hand, if someone exclusively contributes to Quick Docs, so they’d just be getting both badges at once for the same commits and it wouldn’t encourage them to contribute anywhere else.

The levels are 5 (Novice), 50 (Apprentice), 250 (Journeyman), 1250 (Master), and 2000 (Wordstorm) commits, that seems a bit high to me - especially on the lower levels, I’d really like to have the first level to be just 1 commit so a new contributors immediately gets one, and 2k commits is also pretty huge. How about a change to 1, 10, 50, 250, 500 (same as Beat Writer)?

Cookbook

https://badges.fedoraproject.org/badge/commis-cookbook-i

The Cookbook is the project that eventually resulted in Quick Docs, it was meant to be a series of self-contained articles documenting common tasks. You know, like a cookbook. So, like the Beats Writer series of badges, the name is outdated, and I think it’s a bigger issue here than with beats, it really makes no sense anymore and we haven’t used the name Cookbook for very long anyway. Also the badge levels are named after various “levels” of chef and the graphics are chef headwear, which I think is incredibly clever and I love it, but unfortunately it has little to do with Quick Docs.

So what do we do here? Repurpose this for Quick Docs as it is? Leave it be so those few people who got these badges keep them, and start a new Quick Docs series?

The levels here are 1 (Commis), 5 (Tournant), 15 (Grillardin), 30 (Saucier). The original proposal also had 50 (Sous Chef), 100 (Chef de Cuisine), and 150 (Gourmand), but those were never implemented and they don’t have badge graphics. Do we keep those, or something else? Maybe preserve the “1, 10, 50, 250, 500” theme I also proposed for the other two sets?


Let me know what you think!

2 Likes

Hi Petr,

I haven’t been actively contributing to Fedora Docs lately, but I’m really excited to see this discussion about fixing the badge system. It’s a great initiative, and I believe it will motivate more contributors. Seeing this makes me want to get involved again—thanks for pushing this forward!

1 Like