Documentation.. thoughts, ideas, a plan?

[patrick-wc]

Hi Harry and everyone,

I think InuitCSS is by far and away the best framework to use for creating front end web pages, but at the moment its extremely difficult for an new developer to get started, especially compared to something like Bootstrap and Foundation. I realise Harry doesn't really want InuitCSS to be considered in the same category as most other CSS frameworks, stating here that he was worried about developers thinking Inuit was just yet another bloaty framework if they came across it being used in a project. However, I do think there needs to be some more instructions about how to actually use InuitCSS.

For me, the main problem at the moment is if someone lands on https://github.com/inuitcss its far from obvious what to do. I'm not sure about everyone else but it took me a good few hours to read up on all of the modules and issues to get an idea of how to start using it, and even then I had to manually copy and paste the bower install commands for each module. I fear a lot of front end developers would have just given up and used something else, which is a shame.

I spoke to Harry at a conference in London recently and we discussed a bit of documentation I'd written for the agency I work for, so any future developers who work on a project can easily get to grips with InuitCSS. I didn't want to submit a pull request or anything, because I wasn't sure what Harry's plans were or are for the project in general. Today, I've just seen @Csshugs's great kitchen sink demo which would be very useful for newcomers to the project - http://csshugs.github.io/inuit-kitchen-sink/

Basically I just want to get a discussion going on here so we can all collectively come up with something to make the whole process a lot easier than installing each separate module for InuitCSS separately and having to work out what each module does. The current list of modules that @inlikealion compiled together is a great starting point, but it is hidden away and I'm sure feels like a "non-official" way of doing things, so someone who just happens to stumble onto this repo might not feel comfortable starting this way.

I like the idea of a live demo site built using InuitCSS, which @csshugs has done really well. I think we could possibly use that sort of format as a start to some "official" docs (maybe with some more actual HTML examples for each module). This would also be quite a good way of someone taking a look at a completed InuitCSS project, as they could just download the docs/kitchen sink and see how the sass and html had been authored.

@csswizardry You also mentioned possibly doing some screencasts and or a kickstarter campaign. I'd love to help out with any of this. InuitCSS has saved me so much time it would be great to contribute back. I also think that once the word gets out a bit more and people realise how powerful it is, you'll get loads of more users, so potentially more contributors too :)

[rafegoldberg]

have been looking through intuitcss and I know it's what I as a frontend designer want, but as a real world freelancer the lack of well organized, easy-to-find documentation has presented a huge hurdle to diving in. thanks for the links and write up here – definitely would be interested in helping as/if/when this starts coming to fruition!

[renatocarvalho]

+1

[dennisfrank]

+1

[eightyfive]

Same as @rafegoldberg here. Although I dove in quite a bit, it is now a nightmare to teach new programmers in my team. Not because it is too complex, but because they are scared by the lack of documentation.

This is usually where I advise to start: https://github.com/inuitcss/getting-started

But @zerodburn has provided a great link! Thanks @csshugs! http://csshugs.github.io/inuit-kitchen-sink/

I mean this is a pity cause once you learned @inuitcss, you understand this is the way to write CSS.

I would definitely help if this thread ends up in a simple & clear plan to make documentation happen.

By the way nice ITCSS scaffold for your inuitcss projects: https://github.com/gpmd/itcss-boilerplate

[csshugs]

@eightyfive This is also my way of advising people to get started with inuitcss.

@zerodburn @rafegoldberg @dennisfrank @renatocarvalho @eightyfive @nenadjelovac @florianbouvot

You are all invited to contribute to inuit-docks, as this is planned to replace the kitchen-sink, respectively the kitchen-sink will be a part of inuit-docks.

Your feedback will be appreciated here, so I can guide inuit-docks into a direction where it is most helpful for the people.

[eightyfive]

@csshugs great initiative. Frankly from what I've seen, this is awesome. A warm thanks for that.

If you pin point where you need help, I'd be happy to contribute (I am not a native english speaker haha).

[jacquesletesson]

@csshugs Yes it is really helpful. Will read it carefully and let you know what I think.

You should underline ten times this sentence : "inuitcss is not designed to do your work for you, it is designed to help you do your own work faster".

Thank you.

[csshugs]

@eightyfive

I am not a native english speaker

Neither am I, so no worries ;-)

If you pin point where you need help, I'd be happy to contribute

Well first of all, I'd appreciate to gather more feedback from all of you: Is this the right direction; if this is the kind of information that inuit-newbies are after? Is something missing, is there something needless to get rid of? What can be tweaked to be as helpful to the people as possible.

Furthermore, of course the missing content of the modules needs to be written. For the better part, I think this can be adopted from the kitchen-sink. The question here is, how to provide the demos of the objects? I'm thinking of codepens for each of the modules or fiddles like inuit.css v5 provided, so people can play with the modules.

Last but not least: Form follows function. Although it's "just" documentation, the site is not a beauty atm and every user would benefit from a shiny UI that feels nice and fosters the legibility.

Thanks for the feedback so far. Further feedback will be helpful and is appreciated. Be it suggestions/questions in form of issues or actual code delivery in forms of Pull Requests.

[mhauken]

Hi everyone! We, like all of you, love Inuitcss. However, we’re a bit tired of the missing documentation and inconsistencies (namespacing in some packages, not in some). We didn't want long discussions or anything, so we made a fork of everything.

Aleut is a bit more opinionated than Inuitcss. For example:

• We removed @extends alltogether
• Namespacing is not optional, and are not configurable
• Variables that you turn on have the same name as the classes that you turn on
• We consistently use @ to prefix breakpoints, for example .u-1/2@desk
• Simplify mixin names e.g. just font-size()

We wanted something we could use as a good starting point for new projects and make it easier for people to get started with the framework.

You can see it here: http://aleutcss.github.io/ and on github here: https://github.com/aleutcss/ Many thanks to the rest of the team @kmelve and @robinsandborg

[eightyfive]

Hey @mhauken that's really great. I could start a new project very fast, definitely more structure & direction than with raw inuitcss. Thanks for that.

I really liked the starter skeleton full of comments. I would suggest to give it more visibility in your documentation cause it gives good (& simple !) structure for any small to medium size project. That also gives convention over configuration quick win.

Finally, just a note, namespaces, trumps renamed utilities and other opinionated decisions do make the whole thing quite easier to grasp and jump into.

I could actually learn a lot (more) about inuitcss with my first project using aleut. I will definitely continue to try it, my first impressions are positive. I feel in control of my CSS code base.

[robinsandborg]

Cool to hear @eightyfive! We still have a lot left to do in our documentation, and your comments are very much appreciated.

I don’t want to hijack this thread, but you and everyone else are welcome to post your comments, issues and pull requests over at aleutcss or in the offending package.

[nenadjelovac]

@robinsandborg Nice job with Aluet ;)

There is only one thing I suggest changing/removing:

Inuit was left alone a little too long, [...]

While this is true (and I understand the sentiment behind it), it is not what the end user needs or wants to know (at least not on the landing page ;)). They want to see benefits of using Aluet. You need to "sell" it to the end user. Build your copy onto that: What do they get by using Aleut? What is it? What does it mean "scaleable, designless, opinionated framework"?

Then you can go into inuit "shout out" and why Aluet is different than Inuitcss, why it's better and so on.

cc @csswizardry @inuitcss/owners @csshugs

[robinsandborg]

Thanks for the feedback! We’ve revised the intro in accordance with your suggestions.

[nenadjelovac]

@robinsandborg No problems. I just read it. You guys nailed it!! :+1:

[patrick-wc]

Aleut looks really cool, nice one guys.

[csshugs]

Since this repository is now officially deprecated, I close this.

Of course, we have the intention of providing a (real) documentation for the new version of inuitcss. But for this pre-alpha version, we will not take the effort of delivering a proper documentation.

If you have any ideas or suggestions for the documentation, feel free to file an issue in the appropriate repo.

Thank you all very much for your time and your effort of making suggestions and discussing the things here. You are really a big help!