Documentation improvements.

[JimBobSquarePants]

I recently asked the following on Twitter

What do you think stops @ResponsiveBP having that wow factor amongst developers compared to more popular frameworks?

One of the great bits of input I received was that the documentation needed improvement.

Most notably:

• Some of the copy is not too suited for newcomers to the project.
• Navigation / UX in general needs to be better.

There are other issues regarding layout, lack of communication on features, customization, and the tooling involved.

I'm looking for some help improving this. I'm not a UX designer nor interface designer of any sort, my prose is often convoluted and since I know the code inside-out I miss important information that a newcomer would require to make the most out of the framework.

This is where you come in.

If you can contribute ideas, better copyrighting than mine, provide UX improvements, wrestle Jekyll, anything really that you think could improve matters please chip in and do so.

Responsive was written for the community and users at large. As a community we can help push higher standards and make a better web for all.

[tneigerux]

Hello, I realize this is 18 months old but are you still soliciting feedback on your docs? The vision of this project is one I'm completely aligned with, but you're missing some key elements in your docs that could lower the barriers to entry significantly.

[JimBobSquarePants]

Yeah of course! Fire away! 😄

[lsrdg]

Hi, thanks for finding this issue, @tneigerux. I have the same doubt.
About more than 70% of the documentation is already translated, and I have a bunch of notes waiting to be shared. o/

[lsrdg]

Javascript newbie here.
I have been using Responsivebp only because of its css features, but now I am starting to use the javascript and I am struggling to understand the documentation.
Would it be too much to ask for more exemples on the docs?

I think that bootstrap's "wow factor" isn't itself, but merely the amount of (beginner-friendly) resources pointing to it, and all the tutorials, and step-by-step guides.

As an example, my current fight is with the navigation plugin, simply can't find a way to style it properly ( the height) and how to control the direction it is shown (slideDown()/slideUp() would be my guess).
I totally understand if the project wants to be only for developers and, that way skip all the trouble of people opening issues only because they (...like me) haven't done their homework and can't even handle jQuery.

Sorry if that doesn't make sense... I just wanted to share these thoughts that have been keeping me from using Responsivebp in all its strengh, and that's the reason why I haven't published the documention in portuguese yet: it is not fair to share it with others if I am not able to grasp it myself.

Anyway, keep it going! Everytime I get something working properly, it does work properly! (if that makes any sense at all, ehe.)

[JimBobSquarePants]

Hi @lsrdg

I'd like to think I've made the documentation fairly comprehensive (It's certainly better than Bootstrap's own and I cannot replicate the work of thousands of individual developers who've made simple tutorials)

Regarding the navigation plugin, it doesn't slide down or up, only in/out from the right or left side depending on the use of the pull class.

[lsrdg]

Hi @JimBobSquarePants

I'd like to think I've made the documentation fairly comprehensive (It's certainly better than Bootstrap's own and I cannot replicate the work of thousands of individual developers who've made simple tutorials)

Totally agree. Every time something clicked, I could appreciate how succint the documentation was. Exactly because it is not possible to replicate all that stuff, I think it would be a good idea to have more examples. Not talking about rewriting the documentation. But what about an extra section in the line of "how-to", "FAQ" or just a community driven example site of best practices. So far, I've been using the gh-pages branch, but obviously it doesn't cover everything (its examples are as short and concise as the documentation).

Regarding the navigation plugin, it doesn't slide down or up, only in/out from the right or left side depending on the use of the pull class.

Thanks for taking the time and clarifying it. I don't think this kind of question deserves an issue, or even asking on gitter, but they do make a difference for those out there without experience.

By the way, this opinion on adding examples to the documentation is part of my answer to: "What do you think stops @ResponsiveBP having that wow factor amongst developers compared to more popular frameworks?, since I do believe that bootstraps fame and (doc) resources are greater than the library.

EDIT: spellcheck.