Document badge best practices
- Dominant language
- JavaScript
- Stars
- 27.2k
- Forks
- 5.6k
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 46
Description
:clipboard: **Description**
As discussed at https://github.com/badges/shields/pull/1478#issuecomment-446693084 it would be helpful to document some best practices for badges, referencing academic research about badges:
> Something else that could have a big impact on the signal-to-noise ratio of badges would be a “badge best practices” page for developers. Amazingly, there has been some serious research done about badges + projects based on signaling theory and gamification:
>
> - https://cmustrudel.github.io/papers/icse18badges.pdf
> - https://cmustrudel.github.io/projects/badges/
>
> Developers are meritocratic by nature and I imagine would be persuaded by that kind of research, and I think it would be an ideal place to convey the principles behind the Shields origin-vision and encourage them to play along. Along the way, we could give good examples of customization, guiding them how best to use the choice they have.
From @olivierlacan:
> I love your suggestion for best practices @paulmelnikow. This is basically what I moved toward with https://keepachangelog.com/. I'm really hopeful the generator ideas related to the #1899 redesign will facilitate this, since it would make sense to guide people through the process of creating quality badges.
>
>
> It's my job to make sure the original rationale behind Shields is clear and documented. I think we had it in the original repo and it might have gotten lost in the weeds of time.
>
> Here are some fun historical items I managed to dig back up:
>
> - https://github.com/badges/shields/blob/master/spec/SPECIFICATION.md
> - https://github.com/badges/shields/blob/historical/static/shields_white%402x.png
> - https://github.com/badges/shields/blob/historical/static/proportions.png
> - https://github.com/badges/shields/tree/historical#guidelines
> - https://github.com/badges/shields/tree/historical#examples
Since this documentation is for end users, I'd suggest we put it right into the website. We could build it out using React or add some kind of Markdown translation layer. Probably starting with React will be fine.
Contributor guide
Research direction
Read the historical SPECIFICATION.md, guidelines, examples, and the linked badge research first. Then review how the website currently presents end-user documentation and decide whether the page should use React or a Markdown translation layer. Done means a published badge best-practices page covering the rationale, research, principles, and customization examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, react
- Domain
- documentation, web-dev
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100