postmodern/command_kit.rb

README suggestions

gurgeous opened this issue · 2 comments

gurgeous commented

I've spent some more time unironically reading the README and I have a few ideas:

  1. Format ruby code with ruby codefence
  2. Wordsmith the Features section to highlight the most interesting bits. In your opinion what are the 3-5 most important features? Let's put those at the top and expand them.
  3. I wonder if we could get rid of the API section and link to the modules from above (in Features).
  4. At least one badge 😄
  5. Want to stick a logo in there? https://looka.com
postmodern commented
  1. So the reason why I traditionally avoid ruby code-fenses is because only RedCarpet seems to support GitHub Flavored Markdown (GFM) out-of-the-box. I use kramdown for YARD's markdown processing which is pure-Ruby and guaranteed to just-work on any Ruby. Kramdown did recently add a separate parser for GFM, but I wasn't able to shoe-horn it into YARD. Normally I'm kind of a stickler about being able to generate docs locally to inspect the formatting. We could make an exception and add GFM code-fenses so the Examples look less bland?
  2. Normally I like to list the unique features of the library. Perhaps we could compromise and create key Feature bullet-points with sub-bullet points that go in-depth?
  3. Could we still link to each module's documentation in the Examples sub-sections? Maybe put the link in the header name or a "Read more" link below the code example?
  4. Code coverage, maybe a code-climate code quality score (if they don't ding us to much), and maybe a documentation coverage badge?
  5. Is there any fine print for this service? Do they somehow retain the copyright or IP somehow? Provided if I had the time and inspiration, I'd fire up Inkscape and create an SVG logo involving model kits and terminals.
gurgeous commented

OK, I can get back to this now! Work distractions 😄

  1. Let's add 'em!
  2. I'll try it
  3. Sure, good plan
  4. I will investigate
  5. I realized you have to pay... I could make a cheesy one if you want, colored text like I did for https://github.com/gurgeous/httpdisk. Totally up to you.