water.css Better documentation of elements

#76 brought up the point that it's difficult for new HTML users to understand how to use some of the more complicated HTML elements.

I'd love to see index.html (or maybe a separate page) have some sections on how to use each of the elements water.css supports. For example, documentation for the blockquote element could be:

Blockquote

Documentation

Example usage:

<blockquote cite="https://www.huxley.net/bnw/four.html">
    <p>Words can be like X-rays, if you use them properly – they'll go through anything. You read and you're pierced.</p>
    <footer>
        <cite>– Aldous Huxley, Brave New World</cite>
    </footer>
</blockquote>

Demo:

Words can be like X-rays, if you use them properly – they'll go through anything. You read and you're pierced.

– Aldous Huxley, Brave New World

There would be a few parts to this issue:

Discussion on what the content documentation should contain?
Discussion on what the documentation should look like visually?
Writing of the html for this documentation

This is a lot of work to do, so any help on this issue is very appreciated!

May 25 '19 18:05 kylejrp

@kognise suggested an "inline html tutorial" style like Impress.js: https://github.com/kognise/water.css/pull/76#issuecomment-495944966

I personally like the reference style of things like Bootstrap.

Reading more online, it sounds like there are four main types of documentation:

Tutorials
How-To Guides
Explanation
Reference

I can see the four above being:

A tutorial could be inline HTML like Impress.js or a separate page that walks through how to build an HTML page using water.css
A how-to guide is what we already have in both index.html and README.md, simple steps on how to install/use water.css
An explanation would be the motivation behind water.css that we provide in README.md and some of the background on the technical decisions we've made
A reference would be the Bootstrap style documentation

I think we need to expand more on both options 1 and 4.

Tutorial

I think this needs to be accessible and visible to users.

We could inline HTML comments, but we would need to link to the source somehow from index.html.
We could create a separate page (styled with water.css!) that had step by step code examples on how to use it

Reference

Like I said before, I like something like Bootstrap's documentation that provides a list of each component with code examples on how to use it.

Storybook would be an overkill way of doing this by generating documentation from code but it's interesting nonetheless. 🙂

May 25 '19 21:05 kylejrp

can I work on this project?

Oct 06 '19 16:10 prasannabisen

@prasannabisen Go ahead! :smile:

Oct 06 '19 16:10 kognise

Hi! Is the project still open? If yes, can I work on this?

Feb 02 '20 10:02 prachi-28

@kylejrp @prachi-28 @prasannabisen @kognise Anybody working on this right now? If not, I would like to try it.

Sep 29 '20 04:09 ashikvarma11

I'm not sure if anyone has started working on this issue, but I'd love to review any WIP pull requests if you open them up. The "Tutorial" documentation should be a separate pull request from the "Reference" documentation I mentioned before. We can all collaborate once we have a starting point!

Oct 09 '20 04:10 kylejrp

@kognise @kylejrp Is anybody working on this issue? If not, I would like to!!

Apr 09 '21 02:04 misa335

Is the project still up? I would like to work upon it.

Aug 19 '21 12:08 kajal4329

@kajal4329 sorry, got sent to my spam folder! It is, and feel free to!

Aug 21 '21 18:08 kognise

@kognise On it.

Aug 23 '21 09:08 kajal4329

is the project still up?

Aug 25 '21 10:08 mohitgoyal1234

@mohitgoyal1234 yes, it is. I am working on it

Aug 25 '21 10:08 kajal4329

/claim

Aug 28 '21 11:08 ajaykrupalk

Made progress on this in a50c8a01ee85a6ab94db661271b59aee90c6248a, more can be done however.

Jan 21 '22 19:01 kognise

@kognise @kylejrp is this issue still open. I would like to contribute. also Tips and guidelines from people already working are appreciated.

Jul 13 '22 16:07 ghost

Hello, is this project still open?? if yes ,I would love to work on this, and see if I can contribute to the project. I am a first timer to contribute in open source...

Aug 29 '22 15:08 trishit78

Hey. The above issue has been closed.

Aug 29 '22 15:08 ajaykrupalk

Hello! Is this issue still open ? I would like to work on it.

Jan 03 '23 04:01 966422harshi

hello is this issue still open??

Jan 05 '23 07:01 Washdil

is it working?

Jan 07 '23 16:01 priyankarpal

I believe that Improving documents like bootstrap can help many people to learn water.css faster and saves time for people who want to revise stuff in no time. Hey, is this still open? Can I contribute my services to water.css for documenting