Learn Semantic - Call For Submissions
jlukic opened this issue · 19 comments
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,
uinamespace (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
@themeusage for loading intheme.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
uinamespace, 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 ofimageas part of a definition vsui imagePorting 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.
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.
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.
Yo ! Some news about the Beginner's Guide & Ten Minute Overview ? Thanks :)
@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
Alright, yes we are familiar with Pull Requests. You will find our contributions in the Learn-Semantic repo ;)
@jlukic, in addition I am diving into the ten minute overview in the form of a tutorial, does that sound OK?
Sounds good @HDking be sure to look at the legacy docs which concepts need to be adapted for the new documentation. They certainly can be expanded on, but should provide a good starting point.
It might be the case that what I had in mind and what is described with the Ten Minute Overview might differ a bit. So I wanted to discuss this with you.
written above:
- 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.
The thought:
As I am a beginner myself into user interface design and web design/development in general, I had a hard time finding out what Semantic-UI does and especially the power of it. Going through the vast amount of documentation didn't lower the treshold for me.. and maybe also not for other absolute beginners. Maybe a bit like issue #1837 .
So the idea was then to create a short tutorial for the absolute beginner, and during this tutorial introduce the user to the concepts explained in the Ten Minute Overview but then just the beginning part and the what makes it different from the pack. A bit more chunkwise explanation, so to say. And then add more complex concepts in a different tutorial.
I've tried making the AirBnB landing page with only the elements that I could find in the library (and some CSS additions) and I found it extremely easy to implement. See result!
Does this fit in your plan?
Picture from Delft ;)
Anything that is useful to users is fine for me. I am usually more interested in conceptual than practical and I'm sure that comes across in the gaps in documentation.
A guide to building a basic page with semantic ui is quite fine as a choice. I can adapt the legacy docs into another section
Perhaps take users through the whole process of creating a web page with Semantic: from npm install (or zip download) to choosing preset themes and customizing site UI? If you need any help with understanding these concepts feel free to reach out.
An airbnb homepage clone or something like that is great for a tutorial. Mostly I just want to make sure that it is easy to follow and useful. The easiest way is just to send me a draft when you have something so I can give you immediate feedback.
Alright! First draft on Sunday :)
We have a first draft. How do you want to proceed?
Hello, I use this in my sites:
<script src="http://oss.maxcdn.com/jquery/2.1.4/jquery.min.js"></script> <script src="http://oss.maxcdn.com/semantic-ui/2.1.6/semantic.min.js"></script>I find usefull to use a CDN to load the libs, and the expert documentation mention the ones above. It will be awesome if you point that somewhere visible, because the install part using npm is weird for someone coming from bootstrap or a similar framework and we all are used to just paste the CDN tags.
Are you interested in a webpack 2 write up? I have a demo here Semantic UI & Webpack 2 Boilerplate, but I'm more than willing to write a proper guide!
This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 30 days if no further activity occurs. Thank you for your contributions.
Does not look finished to me :-|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 30 days if no further activity occurs. Thank you for your contributions.
Kindly create an icon for "Shopping Cart Reorder" or "Repeat Shopping Cart"