search

kneath / kss

A methodology for documenting CSS and generating styleguides.
warpspire.com/kss
MIT License
4.04k stars 275 forks source link

Add docs badge to README #101

Closed rrrene closed 10 years ago

rrrene commented 10 years ago

Hi there,

this patch adds a docs badge to the README of your CSS documentation tool (which is kind of mind-bending). The idea is to show off inline-documentation of Ruby projects to potential contributors: Inline docs

The badge links to Inch CI, a project that tries to raise the visibility of inline-docs to encourage aspiring Rubyists to document their code. Your status page is http://inch-ci.org/github/kneath/kss/

Inch CI is still in its infancy, but already used by projects like Bundler, Guard, Haml, Pry, and ROM.

What do you think?

benschwarz commented 10 years ago

I'll defer to @kneath on this one, but honestly… I can't see the value in this. KSS has a really small API and this offers no value to me as a user or maintainer.

This might be good for smaller, up and coming applications to show that they're really taking documentation seriously, but thats not how I'd describe KSS…

rrrene commented 10 years ago

@benschwarz The primary idea behind the project is to raise awareness for inline documentation, just like the Travis badge raised awareness for the importance of tests and Code Climate raised the topic of refactoring code.

So the "value" would be provided in a greater sensibility towards documenting Ruby code (and not-so-much for the benefit of the original maintainer). He or she would be more of an evangelist for better docs, to help the community and raise the visibility of inline-docs.

At least that is my goal with this project, but I enjoy any kind of constructive discussion about it!

kneath commented 10 years ago

Definitely an interesting project — this page is a nice gut check for development. Right now I think though, I'll pass on adding this image to my README. I think you nailed it in your intro:

README of your CSS documentation tool (which is kind of mind-bending)

I agree with this — it is totally mind-bending. And while I can distinguish between these in my head, a lot of KSS users probably won't be able to make that distinction. As great as promoting this project might be, I'm going to have to look out for my own users first — and I don't think this serves enough value (for them) to counterbalance the confusion of promoting documentation of a documentation spec.