Having a real hard time understanding the documentation.

[Elliot Hesp]

I'm quite well versed in the web development area, and I have recently picked up semantic UI. However, I'm having a hard time understanding the documentation, finding it fragmented and not descriptive enough.

An example, the sidebar - http://semantic-ui.com/modules/sidebar.html

1. You're first off greeted with an example, with the opening line being:

<div class="ui left vertical inverted labeled icon sidebar menu">

So 8 separate classes, removing one breaks the look of the "icon style vertical menu". There is no description of what these are for, or effect.

Throughout the entire sidebar docs, there's no further explanation of these (or any that are not in that example?).

2. Usage

It's not only until I go onto the 3rd tab I realise I need to wrap my page within the "pusher" class, and have the sidebar separate. Surely this should be the first thing a user should read? 

3. Examples work well, but how are they achieved?

Back on the definition page, there is some example transitions. These work well, and show off the sidebar well. For example, the overlay animation... What do I set, and where do I set it to get this effect over the standard "push/uncover" content? There's nothing in the classes above to suggest this.

I eventually got it working by adding the following:

.sidebar({
 overlay: true
})

However, the console then tells me "Sidebar: The overlay setting is no longer supported, use animation: overlay". Where do I set this (granted, there is a overall lack of Semantic UI knowledge)?

4. How do I set the settings?

There's plenty of settings I can choose from, such as scrollLock, but I can still not work out where to set this?

.sidebar('scrollLock', true)

.sidebar({scrollLock, true})

None of these seem to work... can't think where else I would set this?

---------------------------------------------------------------------------------------------------------------------------------------------------------------------

This is not supposed to be a rant, and I am new to Semantic UI, but I'm having a hard time trying to follow the documentation to do basic things... not only with the sidebar! 

[Kris Korsmo]

Elliott,

I agree with your sentiment that the documentation isn't always as straightforward as I'd like it to be. For example, I'm currently trying to grok the sidebar 'push page' behavior - there's only mention of it in the behaviors, but no example code that I've found, and my trial and error has been mostly error.  Instead, I've been using a custom JS function with jQuery load() to add content to the .pusher.  That in mind, I think Jack has done a tremendous job with not only the development of Semantic, but pretty well in the documentation too.  It's only one guy.  So... I think he's aware of the shortcomings, but without additional support from folks like us I'm not sure how mature any software could ever become. I get the impression that his reality is to choose between ongoing development and [everything else].  With the release schedule he's been keeping over the past year, it's absolutely amazing. I've seen a little of what's to come in 2.0 and I think it's exciting.  The bottom line: the more you tinker with each element the more yo'll get it, even without the docs. Everything will be more polished in time. 

Good luck!

[Jack Lukic]

I'd recommend checking the usage tab for an explanation of required page markup. The definition tab is just meant to show examples of the types/variations available. I'm going to redo the first intro text there to make it a little less confusing of why menu is mixed into the markup.

Basically sidebar has no styling on its own, but just describes content that "sits off canvas and appears with an animation", you can add your own classes to style or set width, or use content that pairs naturally like ui menu. 

The page structure on load should match the whats listed under usage:

http://semantic-ui.com/modules/sidebar.html#page-structure

W/r/t frustration with documentation. As kris explains, I'm currently maintaining many different components (47 currently available ones), build tools, translations, integrations, etc, which means I have to be jump back and forth between different bugs and issues and sometimes lose the correct perspective on how docs may appear to someone who hasn't worked with the code before.

If you see a specific issue with documentation that's not intuitive, or that is confusing, please point it out and I will address it. It's more difficult for me to holistically think about an element's defects without that critical step of constructive user feedback.

--
You received this message because you are subscribed to the Google Groups "Semantic UI" group.
To unsubscribe from this group and stop receiving emails from it, send an email to semantic-ui...@googlegroups.com.
To post to this group, send email to seman...@googlegroups.com.
Visit this group at http://groups.google.com/group/semantic-ui.
For more options, visit https://groups.google.com/d/optout.