Initiative: Terminology / Historical Decisions documents

[SMotaal]

Motivation: In the last few days, while playing catch up to the things I missed in the last 3 weeks, I caught a glimpse of how challenging it would be for our future selves or others going through this repository's issues and documents when trying to pull together various threads.

Initiative: I'd like to propose and take part in an effort to put together terminology / historical decision documents which will allow us to keep track of easy-to-misread terms and how or why certain technical terms will evolve.

Volunteers: @SMotaal @devsnek @bmeck @guybedford

Tasks:

• Pick Format: GD
• Determine Initial Structure: taxonomy-like
• Initial Draft (@SMotaal)
• Create terminology branch (@SMotaal)
• Create Terminology.md Create Terminology.md #158

[benjamingr]

Good initiative!

This should cover static/dynamic resolution, how named exports work, live bindings, differences between ESM and CJS, the various proposals in the past (summarized), where to find what in the repo (links to the use cases for example).

Would you be willing to take charge of it?

[MylesBorins]

I’ve added it to today’s agenda with a 5 minute time box

…

On May 23, 2018, at 2:22 PM, Benjamin Gruenbaum ***@***.***> wrote: Good initiative! This should cover static/dynamic resolution, how named exports work, live bindings, differences between ESM and CJS, the various proposals in the past (summarized), where to find what in the repo (links to the use cases for example). Would you be willing to take charge of it? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#119 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAecVw18HUjcvHcPx4MW8q04n9V9CslUks5t1ajqgaJpZM4UK85g>.

[SMotaal]

@benjamingr I understand the pain more than anyone at this point not to mention that I have a love-hate relationship with terminology.

Count me in definitely

It would be a lot more effective to have one or two other volunteers to increase the odds of it making sense to humans.

[bmeck]

I vote that we use a doc unless there is good reason to have version control. Not the biggest fan of wikis on github.

[GeoffreyBooth]

I was about to nominate a wiki, because it allows Markdown. I find the use cases/features docs hard to read because the code is all mangled in Google Docs.

[bmeck]

@GeoffreyBooth idk, comments are nice and allow issues to be done without needing to spin up a full github thread about specific terms, also it allows a nicer sharing mechanism that github wikis. if formatting is a concern we might be in big trouble since this is a list of terminology and collection of links and not a book with full on examples I would think. If we want to do full examples of each term with code highlighting that might a bigger goal than what I thought this was and would probably need its own project.

[GeoffreyBooth]

Okay, let’s start with a Google Doc then and see how it goes. Or if there’s some Google Drive app that allows editing Markdown, but with all the other features of Docs (comments etc.) that would be ideal.

[SMotaal]

After extensive research of all the options out there for a collaborative markdown editor which either integrates directly with Google Docs and/or offers as close to an experience for the collaborative features often used by the team in Google Docs I think we have a winner:

HackMD — Check out the Features (Fixed: Link was mistyped.)

My personal rating for features:

• Markdown ★★★★★
• Collaboration ★★★★⭐︎
• Integration ★★★⭐︎⭐︎

Pain points:

• Some non-GFM based syntaxes (also a plus)
• No repository integration (uses internal revisions)
• Lacking good description of service offerings (targeting self-host I presume)

More about Enterprise Edition

HackMD on GitHub

[SMotaal]

@bmeck @GeoffreyBooth @devsnek

Please take a look at HackMD because it might be a much needed upgrade to Google Docs in general and not just for this issue. If you have the bandwidth (and bandwidth in general) and want to see how it handles, consider taking it for a spin across multiple incognito windows. It is at least worthy of consideration, and working on Terminology there can be a good prelim.