Improve readme
Closed this issue · 5 comments
💡IDEA: Make the readme more visually interesting. I (@jcbhmr) have my own "style" that I've developed that could be used here, or if there's another way you'd prefer things to be laid out, I'm OK following your lead.
Here's some demos of what some of my readmes kinda look like: fake demo readme #1 fake demo readme #2 and a real world example and there's probably others you can find in my profile too.
Other ideas to improve general "advertising" are:
- Add an emoji to the description like https://github.com/wow-actions does and I do to catch your eye when looking at it
/assign jcbhmr
My personal philosophy is to keep the README as readable as possible in plain-text. In fact, I think Markdown is generally a great guideline for making readable plain-text. There's also accessibility to consider -- ideally, the README should render to something that screen-readers can use.
I've never formally defined these self-imposed rules, but here's a basic idea:
- Images are cool, but shouldn't be required for reading and understanding the docs. Frequently used badges, like CI badges, are an exception.
- Little to no HTML in the Markdown. READMEs with
<p align="center">definitely look prettier when rendered, but I think it harms plain-text readability. - Text styling should be used semantically. E.g.
## headerisn't just a way to make big, eye-catching text, but to define a section, which is helpful for screen-readers.
That's pretty much all I can think of off the top of my head. I wouldn't worry too much about it -- we can discuss the trade-offs between plain-text readability and rendered prettiness further 🙂
Add an emoji to the description
BTW I'm totally up for an emoji, if you have any suggestions 😆
BTW I'm totally up for an emoji, if you have any suggestions 😆
I think one of these: 📚📕📖📘📜 fits the idea of a "docs" sort of emoji. For the description I used this in the readme draft #13
📖 Deploy docs from your source tree to the GitHub wiki
now that I read it again that "the" should be "your"
📖 Deploy docs from your source tree to your GitHub wiki
ill have to fix that in my pr
📖 most resembles GitHub's Wiki icon, so I think I'll go with that. Thanks for the suggestions!
I went with "... to a GitHub wiki"
The reason is that, with the correct access for a token and the repository input, you can publish to any repo's wiki, such as from your personal repo to an org.