Created: 2014.05 (email)
I've been using KSS for the past two or three years and got into them for the same reason as you did, to make sense of a large code base and prevent duplication where lots of developers were involved. In my case I didn't start my first styleguide until the developers had made a mess, but that's another story ;)
The system is not perfect:
I generate my KSS as part of a Grunt documentation task. I use grunt-mustache-render to output a demo snippet of HTML, using dummy data with the same templates which are used to generate the static pages. grunt-includes are used to pull the rendered snippets into the CSS file before grunt-kss generates the styleguide.
grunt-mustache-render must be configured manually for each snippet and demo data must be maintained as the templates change. The CSS only contains a pointer to the HTML, which makes the KSS comments less useful for developers reading the code. The render step introduces a trailing line break which prevents the KSS rendering, so an HTML cleaner needs to be run over the HTML output, which affects the readability of the code.
- logged as kss-node/kss-node#114
Where a rule needs to appear only in the styleguide, for example when documenting a silent class, I wrap the selector in %styleguide. The styleguide links to a separate style sheet which maps %styleguide to body.styleguide
The extra stylesheet is a WET asset, and the grunt-contrib-compass compile time for 2x stylesheets necessitates moving the KSS generation into a separate task, which makes the styleguide less reliable.
- logged as kss-node/kss-node#115
kss-node doesn't support automatic numbering, which affects styleguide ordering where modules are reused across projects, and doesn't provide a way to switch layout templates for o- and m- snippets.
The styleguide template can also be enhanced for use with toggled overlays for CSS regression testing, but this is fiddly to set up and requires manual testing.
I also find that I don't use the KSS {$modifiers} placeholder as much as I used to, mainly because it doesn't seem to work with the mustache templating, perhaps I'm doing it wrong.
Given these shortcomings I'm not 100% sold on styleguides, but with the increased popularity of systems such as patternlab I think they remain relevant, at least for now.