add house style document, put a link to it in other docs #158
Conversation
There was a problem hiding this comment.
It's so good that I feel it could be a bit wasted languishing in the practices directory... I wonder if we couldn't put this front and centre in the readme (and just incorporate those few things from the current readme that his doesn't currently cover).
I wonder if others agree?
|
Minor niggles aside, vg ty :) |
practices/house-style.md
Outdated
|
|
||
| ### Linting | ||
|
|
||
| We lint our CSS, JavaScript, and templates written with DustJS. This helps us to keep our codebases consistent, avoid common logic and implementaton errors, and lets us concentrate on solving problems instead of formatting. |
technologies/css.md
Outdated
| @@ -727,6 +728,7 @@ But in the following example we would not use it: | |||
| [Nature playbook(private)]: https://github.com/nature/playbook | |||
| [bem]: https://github.com/springernature/frontend/practices/bem-css.md | |||
| [a hybrid of OOCSS and Atomic CSS]: https://github.com/springernature/frontend/practices/mosaic-css.md | |||
There was a problem hiding this comment.
probably should remove ref to Atomic?
There was a problem hiding this comment.
Can you clarify what you mean? 😁 is there a page about atomic, or something else?
(that "hybrid of" link is really confusing as it exists as a reference but isn't actually used by anything, and i don't know enough about the CSS stack here to be able to accurately fix things)
There was a problem hiding this comment.
Sorry, I meant change it to something mentioning "utility classes" not Atomic, as we agreed that this new fangled thing called Atomic CSS at acss.io was a possible sauce of confusion ;)
Also I think the link should be;
https://github.com/springernature/frontend-playbook/blob/master/practices/mosaic-css.md
There was a problem hiding this comment.
Bleurgh. You know what, I'm just gonna delete it entirely. It's unused in the text, so it can go. If somebody needs to refer to it they can add some actual text and then put the link ref back in 😁
technologies/javascript.md
Outdated
| @@ -38,7 +37,7 @@ General Principles | |||
|
|
|||
| ### Code For Humans | |||
|
|
|||
| Your JavaScript should always be optimised for readability first, someone is going to have to maintain your code. Most of the rules in this style guide are here to help enforce this. | |||
| Your JavaScript should always be optimised for readability first, someone is going to have to maintain your code. Most of the rules in this style guide are here to help enforce this. See our [house style document](../practices/house-style.md) to understand the rationale behind enforcement of style. | |||
There was a problem hiding this comment.
suggest "first, as someone" or "first—someone"
|
@andrewmee good point, I do think this deserves more prominence somehow -- it is a nice intro to how & why we do things. I do feel hitting the playbook then browsing the (unindexed) dirs is a bit "unguided". |
|
I agree that the unindexed dirs is a problem that's getting bigger as more information is added. I don't think that the house style guide should be in the readme, as it's a tiny bit too specific. I thought last night that it'd be nice to have a "Where do I start" section in the readme, that would provide a path through the content. I haven't yet decided if that should be a full table of contents or just some pointers, maybe with a separate ToC on another page. Leaning towards the separate ToC + starting pointers, so we can keep the readme lean. Thoughts? |
|
Hmmms, how about a "Where do I start" header in the readme, and underneath "Have look at our House Style Guide" (but probably with better wording) might be an idea..? I think the House Style Guide would make a great intro! And maybe having an index page for each directory with a quick summary of the linked-to docs, but that would be another ticket i guess. |
|
👍 |
|
even more 👍 |
|
Right, I think I'm done here. Will worry about indexing in another ticket like Jon suggests. Review pls kthx |
|
LGTM!
…On 24 March 2017 at 13:49, Hollie Kay ***@***.***> wrote:
Right, I think I'm done here. Will worry about indexing in another ticket
like Jon suggests.
Review pls kthx
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#158 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AApvszBnQ3EAoNHP9XNCsWLwwr3gK-EDks5ro8nfgaJpZM4MnIos>
.
|
|
How did I miss this?!? This is fantastic! ✨ |
First shot at creating a house style doc for #151
(also includes a URL fix in css.md)