Move CSS comments docs to CSS directory

[jeffkamo]

Move CSS related documentation to all live in the /css directory

Status: Opened for visibility
Reviewers: @kpeatt @ry5n
JIRA: n/a

Changes

• Comment docs were in a css-comments directory, now it's in css/comments

To Do

• Add an index to the main comments doc
• Decide the folder/file structure (x/x.md vs just x.md) - leaving as is (x/x.md)
• Implement folder/file structure - leaving as is (x/x.md)

[jeffkamo]

@ry5n we could do comments.md. I guess I had it in my head that you treat the url and filename like index.html and stick it in a directory... but the truth is, you can still visit the md file directly and get a fully rendered document no problem.

Short answer: yes, we can do that. Unless for some reason we shouldn't... I can't think of a reason for that.

[kpeatt]

I think so long as our index is manageable, having it in comments.md sounds good.

[jeffkamo]

@kpeatt @ry5n unless there are any issues with this, can we merge this in?

I've started making the rest of the index in a separate branch (indexify-css-documentation), but don't want to PR it until after this one is merged.

[ry5n]

I thought we’d agreed css/comments.md as opposed to css/comments/readme.md. I don’t feel strongly about it, but thought it be a little simpler that way.

[kpeatt]

Agreed with @ry5n

[jansepar]

One reason you might want to call it README.md is because if you navigate
to that folder in Github, it will show the rendered README down below.
On Sep 18, 2014 3:26 PM, "Kyle Peatt" notifications@github.com wrote:

Agreed with @ry5n https://github.com/ry5n

—
Reply to this email directly or view it on GitHub
#24 (comment)
.

[ry5n]

I guess it comes down to the best way to surface these docs. I’m happy with extra folders if that’s going to help people read these. But not sure if putting them in a folder (that doesn’t contain anything else) will make that better. Probably more important to link to other “chapters” from the main readme.

Would be good to know what @scalvert thinks is the better approach.

[jeffkamo]

I honestly forgot about that. My bad, will make a note to determine the preferred method, then implement.

[jansepar]

+1 to linking from the main README. In portal, we had tons of READMEs
scattered throughout the project, many of which I didn't know existed for
years. We've now linked them all from the main README:

https://github.com/mobify/portal_app

On Thu, Sep 18, 2014 at 4:13 PM, Jeffrey Kamo notifications@github.com
wrote:

I honestly forgot about that. My bad, will make a note to determine the
preferred method, then implement.

—
Reply to this email directly or view it on GitHub
#24 (comment)
.

Shawn Jansepar, Lead Software Engineer

Powering Mobile Commerce Growth

mobify.com http://www.mobify.com/ | 1-866-502-5880

[jeffkamo]

@ry5n this is what I've done so far with indexing with rest of the documentation and how they're broken into directories: https://github.com/mobify/mobify-code-style/tree/indexify-css-documentation/css

Thoughts? There are basically five "chapters":

1. Intro
2. CSS practices
3. Sass practices
4. Naming conventions
5. Commenting and inline Documentation

[ry5n]

This looks really good. In practice, most people will read this on GitHub, where the difference between folders with readmes and a flat list of files is immaterial. I think this reads really well, I love the index and especially the “continue to next” link at the bottom of each. +1 as-is.

EDIT: oh I see that’s actually in a separate branch… @jeffkamo were you thinking of closing this and open a new PR?

[jeffkamo]

@ry5n that is correct: my plan is to merge this, then PR that other branch.

[ry5n]

OK, this is ready to merge then I think.