From 8906cba6a607efdb1631d61817c7f7666bb2d9c1 Mon Sep 17 00:00:00 2001 From: jlukic Date: Sun, 13 Oct 2013 17:56:58 -0400 Subject: [PATCH] Rewrite of intro docs --- server/documents/introduction.html.eco | 54 +++++++++++++------ .../introduction/definitions.html.eco | 6 +-- ...ing-started.html.eco => overview.html.eco} | 23 +++++--- server/documents/introduction/types.html.eco | 28 +++++++--- 4 files changed, 79 insertions(+), 32 deletions(-) rename server/documents/introduction/{getting-started.html.eco => overview.html.eco} (85%) diff --git a/server/documents/introduction.html.eco b/server/documents/introduction.html.eco index 67d429105..6ab627ca0 100755 --- a/server/documents/introduction.html.eco +++ b/server/documents/introduction.html.eco @@ -1,9 +1,8 @@ --- layout : 'default' css : 'guide' - -title : 'Introduction' -description : 'Getting to know Semantic UI' +title : "What's Different" +description : 'Separating Semantic from the pack' type : 'Semantic' --- @@ -17,31 +16,56 @@ type : 'Semantic' -

What's Different?

+

+ Designed Completely with EM +
asdoiasdjasdoji
+

+

Every component is defined using em and rem so that components can be resized simply on the fly. Want a menu to get smaller on mobile? Simply have it's font-size change using a media query.

-

Descriptive not Prescriptive

-

Writing front end code shouldn't require learning the naming or programming conventions of a particular developer. Instead of using short-hand, or codified naming conventions, Semantic uses simple, common language for parts of interface elements, and familiar patterns found in natural languages for describing elements.

+

+ Self Explanatory +
Descriptive not Prescriptive
+

+

Writing front end code shouldn't require learning the naming or programming conventions of a particular developer.

+

Instead of using short-hand, or codifying naming conventions, Semantic uses simple, common language for parts of interface elements, and familiar patterns found in natural languages for describing elements.

-

Tag ambivalent.

+

+ Tag ambivalent +
Use whatever html tags you please.
+

Interface definitions in Semantic are tag ambivalent. That means you can use div, article, section, span without affecting the display of the element. Special tags like a, table, td still carry special meaning in certain circumstances however.

-

Powerful tools for expressing groups and collections.

+

+ Powerful tools for expressing groups and collections. +
Don't repeat yourself
+

In English it's much easier to say "There are three tall men" than "There is a tall man, a tall man and a tall man".

In Semantic element definitions can be expressed in groups have shared attributes like size, color, type avoiding repetitive declarations.

-

Portable and self-contained.

-

UI components in Semantic can be used individually, defining optional couplings with other components where their usage intersect. That means choosing to use semantic doesn't mean adopting an entire framework, or rewriting your codebase. You can pick and choose what elements you want to use.

+

+ Portable and self-contained. +
Using Semantic doesn't mean adopting an entire framework, or rewriting your codebase
+

+

Semantic components are written in a singular style, but are not part of mandated overarching library. Only like a couple components? No problem, use only what you need.

+

UI components in Semantic also define optional and required couplings with other components where their usage intersect. That means for example, a popup can check for the existence of CSS animation component before using the fallback javascript animations.

+ +

+ Shared language, different implementations +
Restyle your site without Restructuring it
+

-

Shared language, different implementations

Describing your site's content using a common language like Semantic allows other developers to create UI definitions to match one shared vocabulary. This means you can redesign your website without retooling your html. Simply alter the look and feel of your UI using a different UI style definition.

-

Only the important stuff

-

Instead of giving every possible variation, or behavior under the sun, element definitions are designed to be a starting off point. No oversized downloads, or kitchen sink, just the stuff to get you started.

+

+ Only the important stuff +
Not the kitchen sink
+

+

Instead of giving every possible variation or behavior under the sun, element definitions are designed to be a starting off point. No oversized downloads with optional features you will most likely never use, just the stuff to get you going.

- - Next: Getting Started + + Next: UI Definitions diff --git a/server/documents/introduction/definitions.html.eco b/server/documents/introduction/definitions.html.eco index c5d42a7c2..f2cd59c7f 100755 --- a/server/documents/introduction/definitions.html.eco +++ b/server/documents/introduction/definitions.html.eco @@ -247,9 +247,9 @@ type : 'UI Introduction'
  • Product List
    • -
    - - Next: Element Types +
    +     + Next: Semantic Coding diff --git a/server/documents/introduction/getting-started.html.eco b/server/documents/introduction/overview.html.eco similarity index 85% rename from server/documents/introduction/getting-started.html.eco rename to server/documents/introduction/overview.html.eco index 7c8c8dc58..13c79e2d1 100755 --- a/server/documents/introduction/getting-started.html.eco +++ b/server/documents/introduction/overview.html.eco @@ -2,8 +2,8 @@ layout : 'default' css : 'guide' -title : 'Semantic Coding' -description : 'An introduction to Semantic coding' +title : 'Overview' +description : 'An introduction to Semantic style coding' type : 'UI Introduction' --- @@ -31,11 +31,18 @@ $(document)

    For example a menu may have menu items inside of it. These items are contained as part of the menu definition but do not receive the class name ui because they are part of a UI menu collection.

    -

    Namespacing

    +
    +
    + Home + Inbox +
    +
    + +

    Changing an Element

    -

    Class names in semantic always use single english words. If a class name is an adjective it is either a type of element or variation of an element. CSS definitions always define adjectives in the context of a noun. In this way class names cannot pollute the namespace.

    +

    Class names in Semantic always use single english words. If a class name is an adjective it is either a type of element or variation of an element. CSS definitions always define adjectives in the context of a noun. In this way class names cannot pollute the namespace.

    -
    +
    Home Inbox @@ -48,7 +55,7 @@ $(document)

    For example you might want to include a badge inside a menu. A label inside of a menu will automatically function as a badge.

    -
    +
    Home @@ -102,8 +109,8 @@ $(document)
    -     - Next: UI Definitions + + Next: UI Types diff --git a/server/documents/introduction/types.html.eco b/server/documents/introduction/types.html.eco index 3181f24ef..ddac2bd20 100755 --- a/server/documents/introduction/types.html.eco +++ b/server/documents/introduction/types.html.eco @@ -3,7 +3,7 @@ layout : 'default' css : 'guide' title : 'Types' -description : 'A type is an mutually exclusive change to an element' +description : 'A type is an mutually exclusive version of an element' type : 'UI Introduction' --- @@ -18,12 +18,28 @@ type : 'UI Introduction'

    Overview

    -

    A type is a mutually exclusive change to an element. Types may require different html structures to work correctly, or expect different content.

    +

    A ui definition in Semantic usually contains a list of mutually exclusive variations on an element design. A type is designated by an additional class name on a UI element

    + +
    +
    + Download +
    +
    + +
    +
    + Download +
    + +

    Content

    -

    For example, an icon menu might expect different content like icons glyphs instead of text to be formatted correctly

    +

    Types may require different html structures to work correctly. For example, an icon menu might expect different content like icons glyphs instead of text to be formatted correctly

    -
    +
    @@ -38,9 +54,9 @@ type : 'UI Introduction'

    HTML Differences

    -

    Types may also require different html. For example, a tiered menu needs html specified for a sub menu to display itself correctly

    +

    Types may also each require slightly different html. For example, a tiered menu needs html specified for a sub menu to display itself correctly

    -
    +