Better documentation of elements

[kylejrp]

#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:

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

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

[kylejrp]

@kognise suggested an "inline html tutorial" style like Impress.js: #76 (comment)

I personally like the reference style of things like Bootstrap.

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

1. Tutorials
2. How-To Guides
3. Explanation
4. Reference

I can see the four above being:

1. 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
2. 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
3. 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
4. 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. 🙂

[prasannabisen]

can I work on this project?

[kognise]

@prasannabisen Go ahead! 😄

[prachi-28]

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

[ashikvarma11]

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

[kylejrp]

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!

[misa335]

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

[kajal4329]

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

[kognise]

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

[kajal4329]

@kognise On it.

[mohitgoyal1234]

is the project still up?

[kajal4329]

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

[ajaykrupalk]

/claim

[kognise]

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

[ghost]

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

[trishit78]

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...

[ajaykrupalk]

Hey. The above issue has been closed.

[966422harshi]

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

[Washdil]

hello is this issue still open??

[priyankarpal]

is it working?

[priyankarpal]

can I contribute to this project?

[yoursmanjunad]

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