[MAJOR FEATURE] Glossary

[Chalarangelo]

To enhance the website and repository and provide more value to newcomers that might be unfamiliar with JS, programming, web development or simply some terminology, we will be launching a glossary of JS,programming and webdev terms on a separate page and file. Here's the list of things we need to do before we launch this feature, as well as an incomplete list of terms we should document:

The chores

• Create a librarian script (I'd love to call it that, but we can call it something more sensible), that adheres to our current style, build a README in /glossary. assigned: @flxwu
• Add a keyword_database and its respective script for glossary terms to make search and term tagging more dynamic. assigned: @flxwu
• Update our webber script to generate a glossary page, similar to any tag page.
• Launch with a couple of Medium articles to promote this new feature (I'll definitely write a comprehensive guide to JS and the frontend for newcomers, someone else can write another one).
• If possible, use a script to add short tooltips to our snippets whenever a word from the glossary is present to further enhance the learning experience. Maybe later

The template

Before moving forward, the barebones guidelines for glossary terms are:

• Keep it short and simple.
• File names have the first letter capitalized, are in snake-case and we should create a file for each term. Titles should have the first letter capitalized and be in space case.
• Links might be added later down the line to trusted resources only, such as MDN (and maybe W3Schools), at the bottom of the file as a list.
• Probably no code is necessary and explanation length should be around 2-3 sentences (one line per sentence as usual).

The term list

In general, I would like this to be a complete-ish guide to JS, programming and webdev. What goes in it?

• Terms that are JS-specific (such as keywords - this comes to mind).
• General terms related to programming, algorithms and programming paradigms (OOP, JSON, currying, functional programming).
• Terms that are commonly used in the JS ecosystem (callbacks, AJAX).
• Well-known resources and packages in the JS ecosystem (React, npm, MDN).
• Terms related to web development, HTML, CSS and other complementary technologies (DOM, selectors).

A very incomplete list of terms that should be documented:

• All the JS keywords we can document, add them to the list as we go
• Callback
• String
• Template literals
• Boolean
• Integer
• Array
• Function
• Object
• First-order function
• Functional programming
• Object-oriented programming
• Prototypical inheritance
• Dynamic programming
• Event-based programming
• Asynchronous programming
• Recursion
• Reference vs Value (I don't like the name of this, but we'll figure it out)
• Regular expressions
• Event loop
• Functors
• Factory functions
• Currying
• Class
• Promises
• HTTP/HTTPS
• IP (with v4 and v6 explained)
• HTML
• CSS
• SVG
• XML
• XHTML
• Pseudo-class
• Pseudo-element
• Domain name
• Domain registrar
• JSON
• CSV
• MVC
• jQuery
• React
• Vue
• MDN
• ES6
• Selector
• CI
• Git (and some related commands)
• Repository
• DOM
• Argument
• Closures
• Hoisting
• Node.js
• npm
• yarn
• Express
• AJAX
• SSL/TLS
• Progressive Web Apps
• Constant
• Variable
• Constructor
• Cross-site scripting (XSS)
• Cross-origin resource sharing (CORS)
• Serialization
• Desirialization
• Typescript
• Flexbox
• Scope (and Global Scope, Local Scope etc.)
• Garbage collection
• Mutability/Immutability
• Modules (and all kinds of module systems)
• Responsive web design
• Viewport
• SEO
• Strict mode
• SQL
• MariaDB
• MongoDB
• SQL injection
• Prepared statements
• WebRTC
• WebAssembly
• WebSockets
• WebGL
• Automatic Semicolon Insertion (ASI)
• API
• URL
• URI
• DNS
• UTF-8 (and other encodings, or a term for encodings in general)
• Element
• Stream
• Maps/Dictionaries (I think this could be interesting to explain, but is up for discussion)
• this and bind
• Unit test
• Integration test
• __proto__ and prototype

This list is definitely not complete and MDN has a ton more entries we could include, but I think it's a decent start.

Opinions, suggestions and more ideas for terms are appreciated, let's get started!

[Chalarangelo]

Btw, my list is extremely unorganized, use Ctrl+F to find and mark each item.

[skatcat31]

Hmm... I was gonna suggest why not point to MDN articles until I realized how AWFUL those can be for beginners... This might not be such a bad idea. Maybe call this 30 Seconds of Jargon? Organize it by language then bullet point?

[skatcat31]

Would like to add Element(JS) as a disambiguation so that people might learn about creating Elements programatically

[skatcat31]

So optional examples, and external links... how should we go about this?

[Chalarangelo]

Let's do JS for now and keep it simple, more like a cheatsheet for people not familiar with some terminology and jargon in the industry. Examples are not something I'd consider integral for now, but links to external resources such as MDN sound like s good substitute for people who would like to read some more on each topic.

[fejes713]

#692 - Check if they're okay before merging. They include XSS, DOM, Promise, Recursion and Functional programming.

TODO: fill necessary checkboxes in this issue once changes from my PR are merged.

[Chalarangelo]

Merged both PRs by @fejes713 and @skatcat31 and marked the necessary checkboxes. I'll probably contribute a term or two today, as well. We seem to be moving forward at a decent pace already, this should not take too long until we have a reasonable amount of glossary terms in our little glossary. Keep up the good work, guys!

[fejes713]

#693 - Another one ready to merge.

TODO:

• fill necessary checkboxes in this issue once changes from my PR are merged.
• rethink the name for pass by value versus reference
• rethink if http and https should be under the same definition

[Chalarangelo]

Merged another one, checkboxes have been filled. Naming for both terms is a bit funky but we will figure it all out right before launching the glossary, as we will recheck everything and consider the issues we have.

[skatcat31]

I'm curious if we should go ahead with that merge request or do another glossary note about the automatic instancing of literals?

[Chalarangelo]

We will inevitably end up with a backlog of PRs that we have questions about, I'll mark then as on hold to merge them all in the end. As more questions arise and we discuss them further, we will reach some general guidelines for what to add where and how to phrase it. It's like the good old days of when the project was about a week old and guidelines were changing rapidly, only this time we know how to tackle it better.

[skatcat31]

projects are fun like that

[flxwu]

@Chalarangelo what should the README look like? just a TOC and then a concatenation of all term explanations?

[Chalarangelo]

@flxwu Yep, a simpler version of the main README I suspect.

[flxwu]

Then I'll take over that script 👍 @Chalarangelo

[flxwu]

Do we want a script to generate the keyword_database? @Chalarangelo

[Chalarangelo]

@flxwu My opinion or how I envisioned it anyways:

• library.js called librarian in package.json that creates a README.md in the /glossary folder similar to our main README only simpler
• keyword.js called keymaker in package.json that creates a keyword_database in the /glossary folder similar to our tag database only simpler.

I'm not set on the names, but they sound rather funny, so I kinda like them. If you got better ideas, feel free to comment below. Btw, I think it's important to have the /glossary folder set up with its own scripts instead of appending to existing ones, as this can make use of the stages system in Travis and save some time during builds.

[flxwu]

yep, that's how I'd have done it too. 👍 then I'd like to take over writing the keyword script as well!

[skatcat31]

I'd have called them dewey for librarian and houdini for keymaker but that's just me being a dork.

[Chalarangelo]

Dynamic programming will not be initially implemented, it's an algorithmic technique, it needs a little bit of theory to make sense and is not that extremely important to a beginner. Marking it as complete for now.

[Chalarangelo]

this, bind, __proto__, prototype will not be documented right now. We could work on keywords later down the line as a Phase 2 of the Glossary or let MDN explain them like it always has. Terms like these might also need longer explanations, which is not exactly what I was aiming for originally, as I wanted the glossary to be a quick lookup guide for beginners and people who seem to not know a term or two.

[Chalarangelo]

Marking maps/dictionaries as complete, it's a bit too generic and more about data structures than I'd like. We could come back to this later.

[Chalarangelo]

Also checking MariaDB as we would have to add terms for MySQL, PostgreSQL and SQL Server, too. MongoDB can stay just because it comes up too often to ignore.

[skatcat31]

I did some reviews on them. Otherwise this is a great feature so far and great work!

[Chalarangelo]

Update

As it currently stands, we have a sizeable list of terms ready for the glossary. The keymaker script could use a bit of work and we should make the glossary web script sooner or later. I'm planning to revamp the website, so I will work on the glossary web page and the tooltip idea. I'm also planning to write an article about the glossary and an intro to the JS ecosystem eventually, so we can officially launch the feature in about a month or so.

[Chalarangelo]

After merging #738, the glossary is live here: https://30secondsofcode.org/glossary

[fejes713]

Fantastic! @Chalarangelo

Maybe we should add some kind of search here as well?

[Chalarangelo]

Search and menus are coming to the glossary eventually, I want to revamp the whole sidebar to include static pages and settings, so I'll probably open an issue for brainstorming soon.

[fejes713]

Seems like a fantastic idea for static pages! 👍

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for any follow-up tasks.