Learn Semantic - Call For Submissions

[jlukic]

Learn Semantic

A few people have reached out about contributing to Learn Semantic.

Since there hasn't been any official channel for discussion about the technical documentation of Learn Semantic I thought I'd kick of discussion with my thoughts on the contents and structure of the site.

Site Contents (T.O.C.)

Any content not specifically marked with an author is available for contribution. Any content that already exists is open for edits, additions, & revisions unless otherwise noted.

Preface

• Introduction - (Completed) Short explanation of motivation behind project
• On Language - (I'll write) Detailed explanation of the linguistic ideas behind Semantic. Prescriptivist/descriptivist dilemma. Discussion of CS history & culture and how it affects the development of programming languages.
• What's Different - (Written, could use expansion) Explanation of key features to library, the thing you show your PM/Boss to convince them SUI is useful

Getting Started

• Download - Links to downloading SUI from different package managers
• Integrations & Extras - Integrations broken up into three categories, Front End Integrations (Angular, Ember, etc), Back-end Integrations (Ruby Gem, Composer, Wordpress, etc), and extras (PSDs, AIs, etc) ported from this Integrations Wiki.
• Beginner's Guide - Guide to using Semantic assuming limited development knowledge. Path of least resistance for getting set-up. Links to core concepts as 'next reads'
• Expert Guide - Guide to using build tools assuming knowledge of command line interfaces, current web technologies. Important 'next reads' outlined
• Ten Minute Overview - Adaptation & enhancement of the three pages of legacy docs introducing core concepts into a single doc. Showing basic princples through code samples.
• Terms Glossary - Discussion of terms used in the project, and their meaning. E.g. "definition", "variation", "type", "component", links to sections where concepts are discussed more in-depth when appropriate

Developing

• Customizing - Guide to overarching work processes & guiding principles when developing with Semantic. Quickly prototyping with SUI vs deliberate building for continued future maintainance & redesign.
• Extending - (Needs POV discussion and writer) - Guide to how to add your own custom UI components alongside existing framework UI components. Difference between theme and component.
• FAQ - Frequently asked questions about Semantic UI with QUICK answers, or links that point to extended discussion in other articles
• Bugs & Support - Links to community sites, how to go about submitting a useful bug report on GitHub issues (adding a test case, adding bracket tag with component), using stackoverflow or slack for quick support.

Usage & Practices

• Language - (Needs adaptation and new content) Explanation of descriptivist language and naming conventions, considerations when naming something new. Ported from legacy language style guide
• HTML - Discussion of class name word, word order requirements, ui namespace (parts of component vs component). Discussion of tag ambivalence, and exceptions: usage of <i> <a> <td> etc. Explanation of types, variations and how they connect to class names.
• CSS - Discussion of source CSS/LESS conventions. Omission of vendor prefixes in source. Omission of mix-ins, nested rules, and other preprocesser features. When to use variables versus fixed values in css. Variable scoping explanation, and links to other sections discussing scope. Brief explanation of @theme usage for loading in theme.less //---------- #1559.
• Javascript - (Needs adaptation and new content) Discussion of "behaviors" in Semantic UI (aka methods), coding conventions. Discussion of javascript module format
• Techniques - Porting of CSS techniques and JS techniques]() from legacy docs.

Theming

• Overview - Introduction to theming inheritance, folder structures, variables, overrides
• Creating Themes - When and how to create a theme, practical example. Theme distribution.
• Site Themes - Detailed explanation of site themes, when to use site themes instead of packaged themes. Table of most frequently adjusted variables (Font size, grid column count, colors). How to use all three levels of theming together, for example using a "material" theme, but then adding site variables on top of theme to customize colors etc.

Definitions

• Overview - Explanation of definitions, types (mutally exclusive) vs variations (mutually inclusive), states, etc. Discsusion of "kingdoms" of definitions (Elements, collections, views, modules, behaviors).
• Namespaces - Discussion of the ui namespace, difference betweens parts of a component and a UI component. Discussion of component coupling, usage of multiple components on same html element and possible issues with inheritance. Explanation of stubbed classing, i.e. use of image as part of a definition vs ui image Porting of some content from
• Elements - Description of a "ui element", common parts of element definition, plurality, examples
• Collection - Description of a "ui collection",
• View - Description of a "ui view", parts of definition, examples
• Module - Description of a "ui module", ported from legacy docs
• Behavior - Description of a "ui behavior", distinction from module, links to behaviors discussion

Project

• History - (I'll write) Explanation of the adaptation of SUI from previous work with Quirky. Brief professional background, the paradox of 'authoring' a community OSS library, BDFLs.
• Contributing - Explanation of CLA, links to GitHub enhancements/bugs by milestone, links to style guides, links to contribute to official framework integrations
• Translating - Explanation of Transifex, links to how to use the editor and sign up. Some basic text written in wiki already
• Donations - (I'll write) Explanation of financial situation (OSS maintained by author full-time living off donations), list of donators, total funds raised. Explanation of project funding goals and progress toward goals. Most likely this will be explicitly linked from the readme.

Contributing Process

Choosing a Topic

If anyone is interested in contributing. It should be a fairly simple process.

• Leave me a note in this thread if you are interested in taking responsibility over a specific guide and add a deadline when you think you can finish a draft (Please no longer than 1-2 weeks ahead).
• If you see a gap in the TOC and want to recommend a new topic please let me know your ideas, and a brief outline of what content would be included (a couple sentences)
• Provide an e-mail if possible so I can reach out to you
• On your self-appointed deadline I'll reach out to you to see how your progress is going, if you need more time, editing, or help integrating it into the docs code base.

Writing a Guide

LearnSemantic can parse HTML and Markdown (using DocPad).

If you are comfortable with markdown but prefer not to run the server, you can just e-mail me a markdown file with a draft on your approved subject.

If you prefer to run the server you can check the readme for running the server, then simply submit a pull request with your additional guide in server/documents/. Using the server gives you the added benefit of seeing your docs in place as others will see them.

Editing, Typos, etc

Many of the guides could use proofreading and editing. This is a fairly simple way to contribute if you don't have time to help with writing guides.

Adding edits can be done directly through GitHub.com using Pull Requests.

• Go to the documents folder in the LearnSemantic repo
• Find the source file that matches the guide you are looking to edit
• Use the inline tools to edit the file.
• Create a Pull Request (should occur automatically when saving without repo permissions) for the repository with the changes to the document

---

Thanks everyone. I'm excited to see what we all can do together.

[MiracleBlue]

I'm very excited to see more Semantic docs and integrations. Hopefully I'll have some time soon to contribute something ember related to Semantic.

[p-hennessy]

IMO, there should be a section for showing off example sites built with Semantic. It would be a place to see what a website could be using Semantic, as well as give developers a good example of how to combine components and how to structure their markup correctly.

[Alekusu]

Yo ! Some news about the Beginner's Guide & Ten Minute Overview ? Thanks :)

[phuckien]

Hello @jlukic, we (me & @HDking) would like to work on the 'Beginner's Guide'. Is this ok?

[jlukic]

@phuckien Yes absolutely, just send me any progress as you come along. If you are familiar with Pull Requests, you can submit a PR for the Learn Semantic Repo.
https://github.com/Semantic-Org/Learn-Semantic

If not markdown is fine

[phuckien]

Alright, yes we are familiar with Pull Requests. You will find our contributions in the Learn-Semantic repo ;)

[HDking]

@jlukic, in addition I am diving into the ten minute overview in the form of a tutorial, does that sound OK?