The code or document dance

Documentation has been a challenge for me. With no professional training, it's a wonder why I'm bent on looking professional. I've struggled with site structures (for the site that would eventually host the Slick library), tutorials, overviews, marketing statements - for OpenSource no doubt! How do I share this so people fully understand what it does. Speak vision? Speak functionality? Speak features? Speak benefits? Develop demonstrations that speak for themselves?

Whatever my initial approach for describing what this thing does and how it works, I usually digress into technical details or opine Slick's features and benefits. It's hard for me to communicate one thing, when I haven't said all the rest first (again, the vicious circle and then you're 30). Single sentences become whole paragraphs, and paragraphs become pages.

Nevertheless, seeing how Slick is still incomplete (I haven't touched the code in months), I've decided to dust off the old girl and write some routines this weekend. Not to say this entire puppy will be done soon, but I'd rather advance it's functionality than promote it's form.

I'll share my pitfalls in coding a large library like Slick another time. Plenty more to come!