tc39 / tc39.github.io Goto Github PK

This issue is meant to collect usability problems that come up when people visit the site.

If you find that you are not getting what you need from the site, please comment here and let us know what you were looking for and where you would expect to find it!

someone recommended that we include a modal or some form of info box that invites people to make comments / suggestions on how the website works. I think this is a great idea. We can include a link to this repo and a short message. thoughts?

I'd like to have a small travis configuration to (at least) do the linting inside PRs.

As an invited expert to the July 2018 TC39 meeting, and someone who had never been to a TC39 meeting before, I'm relying on both discretion and gut feelings on what to do outside of the specific subject I'm speaking about. Generally, I feel I should keep quiet, but I keep hearing ideas and proposals that I'm interested in participating in.

Mostly I'm participating via the IRC channel.

IMO the landing page should give a glossary only on the present state while other pages / other sites should give a full look on the history of the spec.

IMO the plain text could be spiced up with some illustrations

When interacting with the page menu (in non-phone layout), the font weight change on link hover causes menu items to shift sideways and submenu containers to expand and contract. ("Contribute" and its subitems demonstrate this the most significantly.)

We could make these items / containers fixed-width, but I would personally vote for keeping a normal font weight even on hover—the color change and underline is more than sufficient as a visual cue. 😄

It's a common pattern to have a footer with all the main internal and external links of the site.

As per our meeting today, we should do the following:

• remove the twitter link
• introduce a way of counting visits to the page without holding on to user data ( we were thinking of an old school hit counter)
• Update link to the github organisation, not the project on github specifically
• remove inactive proposals and finished proposals from the specs section

Each tag should have a hover description:

here are the proposed texts:

• dates -> hover description: "Last presented on ...."
• tests -> hover description: "has tests"
• specification -> hover description: "has specification text"

We should automatically lint staged files. This should prevent PRs with inconsistent code formatting.

This issue on @littledan 's outreach groups repo brought into sharp focus that we could be doing a better job of "advertising" (for want of a better word) the work we are doing to connect with the community. If we're held back by a need to formalize activities with Ecma International, I'm happy to start getting on that.

We should automatically install the npm dependencies, when someone executes make install.
I'm not sure how to handle the case, when npm is not installed on the users machine or not the right version.
But this would automatically activate husky, lint-staged & stylelint, so we don't have to deal with code formatting in PRs.

Ideas? @codehag

When accessing the website with a bad network connection the icons are potentially invisible. The user might miss that there is a navigation icon, because the icon itself could not load.

We should provide a fallback by using native symbols.

Proposals:

Menu icon: ☰ (☰)
Accordion caret: ▼(▼)

Edit: they seem to be missing completely right now 🤔

Edit2:
missing on tc39.github.io/beta
visible on tc39-beta.netlify.com

It would be nice to have a short glossary on hover for words that we use on the committee that might not be clear to outsiders.

Here are a couple that we have gathered so far:
Delegate - A person who represents an ECMA International member organization
Member - An organization that has joined ECMA
Champion - A person who presents and supports a proposal through the tc39 process
Contributor - A person who is working towards making a proposal a reality
Proposal - a proposed new language feature that has not yet been added to the language
Ecma international- A standardization body that takes care of the ECMAScript spec
TC39 - Technical Committee 39, a committee organized by Ecma international
ECMA-262 - the official name of the ECMAScript specification
ECMA-402 - the official name of the internationalization specification

Any other suggestions?

I noticed that links are pretty low contrast on the beta site, and they'd benefit from a more impactful color than aqua/light blue. You can check out the ratio here, it's 1.86:1 where it should be at least 4.5:1 for readability - http://contrast-ratio.com/#%2377ccbb-on-%23fefefe

Using the Chrome color picker I was able to pick a contrasting color that meets contrast guidelines: #038067

We should think about how to place the Ecma international logo. If anyone with design experience can chime in it would be great!

Here is my haphazard attempt:

IMO text should be at least managed in separate, human readable documents or better in a CMS.
I had good experience with Gastby + Netlify CMS.

We should update our text blurbs to make it clear that TC39 is not a stand alone committee, but is part of Ecma International. Here is the proposed text change:

Replace “TC39” in the following sentence with "Ecma International's TC39"

“Ecma International's TC39 is a group of JavaScript developers […]”

The official name of the standards organization that TC39 is part of is now "Ecma International". They no longer used the all caps "ECMA" (except in document id's like ECMA-262) and no longer consider "Ecma" to be an acronym for "European Computer Manufactures Association".

For more history of the name see https://www.ecma-international.org/memento/history.htm

Keep in mind that TC39 is not a standalone organization and its authority to create standards comes from Ecma. There really should be a link back to the main Ecma website and and probably a statement that organizations that want to participate in the ECMAScript standardization process need to become Ecma members

For examples, we add a section that says "show example" which indicates that clicking it will expand into a long code block:

This was mentioned in #101

It is currently not ideal. If anyone has ideas about how to adjust this, let's iterate on it. I tried what was suggested in #101, but I found that pulling it to the right moved it out of sight line when reading the descriptions.

Current version:

Closed

Open

Colour scheme, (and maybe fonts) should match the new TC39 brand identity.

In the designs we have a long form about section and specs section. I started thinking about what kind of information could be added there and there is some good stuff we could summarize. What would be great is to have feedback on what we need.

Here my notes on the two sections in question:

Information that can be added to the long form of the about:

• taking care of ECMA-262, ECMA-402, ECMA-404, ECMA-415
• summary of organizations that take part, (commercial, ngos, etc)
• invited experts
• the many contributors who comment, improve, and give feed back on proposals

Information that can be added about the specs:

• the proposal process
• short summaries about each stage.
• which stages are safe to use
• where the specs are hosted, and how the specs are integrated
• what the conventions of the spec are, and how to read proposal spec edits (probably as a link out?)

@zoepage @littledan thoughts?

I think one of the most confusing things for newbies is the JavaScript/ECMAScript distinction. I would suggest explaining it.

This could be done with one of two approaches:

1. Use JavaScript throughout the site, and have an appendix or FAQ or similar explaining ECMAScript
2. Use ECMAScript throughout the site, and have an appendix or FAQ or similar explaining the connection to JavaScript

I think (1) is more friendly toward web developers. (2) would, IMO, require some extra work to quickly clear up the confusion. For example the large homepage text saying "Specifying ECMAScript" that was shown on the slides should be something like Specifying ECMAScript <small><a href="...">What is ECMAScript and how does it relate to JavaScript?</a></small>

Some proposals have multiple scripts. We should make this possible to do.

http://tc39-draft.netlify.com/: Not found

How do we want to work together on this?
Using BEM and ITCSS or something else?

This happens all the time - someone proposes breaking changes and his ideas are rejected because they break the web.

We should have authoritative document explaining why non-backward-compatible changes are forbidden, when such changes can be accepted and how one can rewrite thheir idea to make it backwards-compatible.

We are planning on having a crawler collect information from proposals for display. At the moment the following are necessary:

• title : text string
• short description (max 150 characters?) : text string
• champion : array of strings
• author : array of strings
• test : URL
• specification : URL
• code sample : code block (text string)
• resources (github repo, etc) : array of urls
• proposal group (if applicable) : proposal group name

Is anything missing from this list?

<edited to add proposal groups, code samples, and types for the information>

Both upcoming agenda and recent meeting notes links are outdated. Is it intended to have links to most recent agenda and notes? In that case it'll be better to parse agendas and notes repos. Also notes are usually get published 2+ weeks after meetings (ToC and summary for them are even later).

In #101, it was suggested to iterate on the above the fold design, as the menu item had changed. This bug is opened for that purpose:

Current alternatives that I tried based on the feedback as I understood it in #101

The website looks like it's in pretty good shape. Should we launch it to tc39.github.io?

After discussing with @codehag about some requirements around scraping data for use with the website, I thought I'd demonstrate a working example of this with Jekyll + GitHub pages:

The documentation site (http://www.chaijs.com/) for the Chai testing library currently uses Jekyll. We have a few parts of the site that are automatically updated - for example http://www.chaijs.com/plugins/ is a list of community maintained plugins, which gets updated every day using a nightly build on Travis-CI. Additionally http://www.chaijs.com/releases/ is automatically generated nightly.

Travis has the capability to run schedule builds (the "Cron Jobs" section of settings offers this) and so chais/chaijs.github.io on Travis is configured to run every 24 hours, provided there hasn't already been a commit to master in the last 24 hours.

This means that the CI build job is run at a minimum interval of 24 hours. Part of that build script is generating plugin data:

https://github.com/chaijs/chaijs.github.io/blob/24af0083ee0ec7bafe117fec4e9c09dd4e567575/Makefile#L41-L46

Then there is some makefile hackery to say if the Make task is being run on Travis, on the master branch, build the site and if the working directory is unclean, then commit the new changes to master.

https://github.com/chaijs/chaijs.github.io/blob/master/Makefile#L93-L115

Hopefully this provides a good example of how Jekyll sites can have some "dynamic" data (for certain values of "dynamic").

It should be explicitly mentioned that the spec is called ECMA-262 with a proper link.

https://www.netlify.com/

I would be useful to have sections for code samples and if any polyfill?

I am trying to maintain the code samples at es-next.

From the menu, I see some ideas for the organization of pages. For the most part, I really like this organization; I just have a few suggested tweaks:

• I don't really understand the difference between "contributing" and "guides"; maybe they should be merged
• The survey data shows that many people want to give feedback on proposals rather than champion their own. Let's see if we can organize the website this way; "championing your first proposal" sounds like a really inviting title, as if everyone champions proposals; maybe this should be just "proposal guidelines"
• I'm not sure if "running the tests" is a common path; this is a setup that happens once per implementation. Maybe you mean "contributing tests" (as you have in the contributing section)
• I don't think we have a programme of work :(
• For "archive", I'm not sure if it's useful to link to those old versions; maybe we could just have one link to the Ecma page in general
• For the current specification, link to the current draft specification on GitHub (and call it out as a draft), rather than the previous annual specification.
• I'm not sure if we should paste the set of current proposals on the homepage. It seems like many people are already scared because they think they should understand all of the proposals to contribute (which is completely not the case; no one understands all of them). It might be better to leave it on a separate page, either in its current location in the proposals repo or a prettier version of it in a separate page on the new site
• For "process", I think we should write a page which is a more approachable, high-level introduction, as well as case studies for how other proposals have gone through the process
• There should be some link to the ecma262 and ecma402 repositories, which are where a lot of the work happens (maybe under resources?)
• For "who", I'd focus less on the formal Ecma structure and more on how TC39 attendees include so many important stakeholders

At the moment of writing the H1 page heading is "Specifying JavaScript". It feels like the amount of information the visitor obtains from this part of the web page could be increased to make the header more valuable to the reader. As such it would be great if the website presented to the visitor a complete information package about who does what.

An idea would be to do the following:

• add a subheading explaining TC39 just by expanding the term
  (now the the visitor knows who we are talking about and has the explanation of TC39)
• reshape the H1 message into a SVO (subject-verb-object) form in order to provide more information about who does what
  (now the visitor knows that tc39 is a technical committee and it is responsible for shaping javascript).

ps. the word shape is just an example as it felt warmer in expression than the technical specify. Not sure about the fullstop/period at the end of the H1.

We are discussing what the table layout below the fold should look like. Here are some early thoughts:

Table layout - new columns for current implementations

A commonly requested feature was a page that tracked the current status of where a proposal was in terms of being implemented. We have this partially finished with the proposals md, but there is more information that was requested. For example, a caniuse breakdown browser by browser of where features were available natively.

Perhaps a table with:

• the proposal,
• the authors and champions,
• the current stage, and
• the implementation status

Combine babel and the rest of the browsers status

• How do we do this? Do they have apis? Investigation time!
• (Chrome)[https://www.chromestatus.com/features#javascript]
• (Firefox)[ https://platform-status.mozilla.org/ ]
• (Edge)[ https://developer.microsoft.com/en-us/microsoft-edge/platform/status/ ]
• (Babel)[ https://github.com/babel/proposals -
• How do we keep maintenance down? Are there apis we can use, what resources can we rely on?

Text content
is it what we need, do we need more information?

Design Questions
Icons -- these don’t look great, what can we do to make it better?
How do we improve readability? (suggestion, alternating background colors in the table)

It goes to an old spec without current features and error corrections. It should go to https://tc39.github.io/ecma262/.

Since we are going to make this available publicly, our readme could use a little work:

• double check the docker configuration
• add a description of the site and its purpose
• include a link to the code of conduct
• write up a CONTRIBUTING.md doc (atom has a nice example: https://github.com/atom/atom/blob/master/CONTRIBUTING.md)
• add a license

https://developers.google.com/web/fundamentals/accessibility/

This is a proposal to update the current design including changes in the information architecture.

Above the fold, we'd have the 3 main topics that include the 4 main navigation points.

1. TC39 (about the project)
2. specs / contributie
3. state of proposal

The 3-grid copy is a "show-stopper" that would be supported though illustrations or icons and should give the user a first idea of the content of the site. The copy also gives various entry points though links to the internal content.

The navigation on the bottom of the page indicates the lower emphasis as the user should be focusing on the content above fold. While you scroll below the fold, the navigation bar would scroll up until it reached the top. It would stick to the top then and change the color to orange background and dark typo(#222). It would and also stay like this on every sub page.

I'll make more mocks for tablet and mobile view in the next few days.
Please note, this is a mockup and there are still small issues that will be fixed later on.

Thanks!

Requirements:

• Needs to make use of .md files for ease of editing
• shippable with github pages

Currently using jekyll. What are some other solutions, what are the benefits and problems with them? (e.g. https://www.11ty.io/)

I've added a few new labels to the repository. You can find them here:
https://github.com/codehag/tc39-web-draft/labels

I hope they'll help to structure things a little bit more.

If you have questions or would like to add / edit something else, here is the right place for input! :)

What it says on the tin! Many people are unaware of the monthly planning call and that it is open to all. Let's add information about what kind of stuff is discussed and how to join.

The popup obscures the content below it even though it is hidden.

The current implementation for hiding it hides only the label using the opacity. The links/content underneath are still obscured by the popup preventing any interactions. The parent (div.popup) needs to be hidden instead of the label, which might require JS.

And I would also like to mention that the keyframe moving has visually no effect because while the 90% mark to move the label is reached the label would have an opacity of 0.1 which makes it nearly invisible.

So, I tried the below

cd tc39-web-draft
make install      # install the site's Docker image
make build        # run Jekyll and rebuild site folder
make serve        # run Jekyll, serve site on localhost:8000, and watch for local changes

But not able to access http://localhost:8000 via browser, even though dockerfile has EXPOSE 8000, am I missing something?

$ docker --version
Docker version 18.03.0-ce, build 0520e24

$ uname -a
Darwin LM-BNG-22004407 16.7.0 Darwin Kernel Version 16.7.0: Sun Oct 28 22:30:19 PDT 2018; root:xnu-3789.73.27~1/RELEASE_X86_64 x86_64

There was some discussion at yesterday's meeting about proposal grouping. For example, classes proposals really work together and do not make as much sense separately. This issue is here for discussion of this topic.

Some idea:

• dedicated pages
• tagging grouped proposals with for example proposal-group--class or something similar and displaying those together

Depends on #59 -- We want to survey all proposals (starting with stage 3 for now) for what kind of information is missing. For each proposal we can use the checklist outlined in #59 and check off what is available in the proposal and what is missing.

Once that is done, add it to this issue, and open an issue on that proposal with which fields are missing