How do we handle "reminders"?

[mirisuzanne]

Some remedies (like #7, or #11) are useful in some cases, but would be dangerous as universal defaults. As a first step, we've proposed putting those in a secondary reminders.css file - a reminder for authors to consider what defaults will work best for them. Is that the right solution for a project like this one?

I like the idea of reminding authors to consider certain defaults before applying them, and providing context to learn more about the issues involved. Will it work, or will authors simply default to importing both remedy.css and reminders.css globally? If we want to put up further roadblocks, there might be a few other options:

• all reminders are commented out by default, and need to be explicitly uncommented
• reminders live in a markdown file, and on the website, but are not available directly as a CSS include
• other ideas?

[jensimmons]

I do think this is the right way to go for us. That way we can include all the "frequently a good idea, but maybe not always" code in this project, without making assumptions about people's work — like that they are using a latin-script language, or that they aren't doing something sophisticated with animations.

I lean towards putting this code into a CSS file, and not a markdown file. Especially for folks who don't really get what markdown is. This is CSS. It makes sense for it to be in reminders.css — or another name.

I do want to include comments throughout, explaining what each thing does and where to learn more. Put the educational piece right there, inline.

It's likely a good idea to comment out all the code by default. That way if someone does just drop the whole thing on a site, it doesn't run this code. It also gets the message across — this code is opt-in. You need to read through it and decide whether or not to use it.

This makes me think of @johnalbin's work. His starter-kit projects are always terrifically documented, and include a lot of options that are commented out by default. https://www.drupal.org/project/zen

Like this: https://github.com/JohnAlbin/zen-grids/blob/master/sass/zen-grids/_background.scss

I've used his projects many times, and always found it easy to read through stuff, make decisions, and remove the opening & closing comment markers around each chunk to "turn something on".

[mirisuzanne]

It looks like he's using KSS syntax for that documentation :)

I'll comment out all the reminders for now. Also totally open to renaming that if you have ideas. something we'll want to resolve before 1.0.

[tigt]

HTML5Boilerplate tackled this issue by commenting out code that needed reminders/dev thought — that might work out well here, at least from a “first, do no harm” perspective.