The Wayback Machine - https://web.archive.org/web/20201203030442/https://github.com/kognise/water.css/issues/80
Skip to content

/ water.css

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Better documentation of elements #80

Open
kylejrp opened this issue May 25, 2019 · 6 comments
Open

Better documentation of elements #80

kylejrp opened this issue May 25, 2019 · 6 comments
Labels
enhancement good first issue hacktoberfest

Comments

@kylejrp
Copy link
Collaborator

@kylejrp kylejrp commented May 25, 2019

#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
Copy link
Collaborator Author

@kylejrp kylejrp commented May 25, 2019

@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
Copy link

@prasannabisen prasannabisen commented Oct 6, 2019

can I work on this project?
@kognise
Copy link
Owner

@kognise kognise commented Oct 6, 2019

@prasannabisen Go ahead! 😄
@prachi-28
Copy link

@prachi-28 prachi-28 commented Feb 2, 2020

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

@ashikvarma11 ashikvarma11 commented Sep 29, 2020

@kylejrp @prachi-28 @prasannabisen @kognise Anybody working on this right now? If not, I would like to try it.
@kognise kognise added hacktoberfest and removed help wanted labels Oct 1, 2020
@kylejrp
Copy link
Collaborator Author

@kylejrp kylejrp commented Oct 9, 2020

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!
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement good first issue hacktoberfest
Projects
None yet
Milestone
No milestone
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
@kylejrp @ashikvarma11 @prasannabisen @prachi-28 @kognise
You can’t perform that action at this time.