② Setup the build system for compiling the data structure into HTML about web-app HOT 12 CLOSED

I'm personally a fan of Eleventy (which has been installed, but its functionality has not been used) as it's less reliant on JS, which makes it intrinsically more accessible and performant.

I could be misunderstanding what you mean here, but the API isn't a dependency for the website so much as it is a future plan that we need to account for.

from web-app.

The latter version would also have the problem that we have a flash (or longer timeframe) of full content, and once the JS is parsed, the majority of the content would disappear. Plus the site we send initially might get huge pretty quickly.

If personalisation is desired, we will not be able to get around a more complex server-side solution.
We could maybe go a hybrid route. We render all known pages (e.g. the index, alphabetically sorted pages and so forth) as part of a build step on the server and store them as HTML. This will give us blazing fast responses for those. For the personal definition pages, we take the first request as a signal to store the rendered version, render it and save the resulting HTML on the server. The first response will have the overhead of rendering (shouldn’t be too much, anyway), but for every subsequent request to that specific combination of definitions, we will have the same performance as for the static pages.

Other than that I have been thinking a bit about the build and data structure and given that search will become an integral part of the app, I think we should keep in mind to be able to integrate a service like Algolia. They are blazingly fast, seem to be a friendly company (Disclaimer: there are no friendly companies) and would a lot of the complex problems, such as typo tolerance and synonym search. As their JS SDK is pretty hefty, a server-side wrapper around it would also be essential.

Long story short: Given the desired feature set, I think we will not be able to hack our way around a server.
Using Express might be a viable solution here.

For the frontend, please no React. Facebook does not deserve the honour to be integrated into this project.

from web-app.

Communicating one entry point for new definition seems to make much sense, +1 for that. I’ve also thought about this for a bit. My idea was a form on the website which triggers new issues, opened by a bot (probably). That would take the «need a GitHub account» barrier away. But broadening/channeling the means of participation is another issue/discussion, I think.

I will for now take the data we have, abstract it (leaning on @good-idea’s example structure in #13), and a build step to create the index.html file. Looking forward to refine that with y’all going forward.

from web-app.

I will have look if we can replicate the data structure we have and need with Markdown and some Frontmatter. Seems like a very pragmatic approach for now. Accompanying it, Eleventy seems like a good choice. I heard it is pretty good at generating sites.

from web-app.

@tatianamac I think we can close this?

from web-app.

If we use a static generator like Gatsby, the frontend wouldn't even need to use the API for the website :)

from web-app.

but the API isn't a dependency for the website so much as it is a future plan that we need to account for

Yeah, we're on the same page here :)
As long as the whole dictionary is in the same repo, the builder wouldn't need to query any API.

If we were to do this ground-up with something like React, it would need to be fetching data from the browser. But, I agree that a static site is much better - I don't see any benefits of an SPA at this point. I think we'd only need to worry about linking up the site to an API when (and if) we got into things like user accounts, upvoting, etc.

from web-app.

Just had a thought - using a static site generator won't work for the personalized URL - it would need to generate a page for every possible combination of terms in the dictionary. As the dictionary grows, the build times will multiply. If there are 100 terms in the dictionary, and the limit is 3 terms in a url, i.e. /AsianAmerican+pan+something, that's roughly 1 million HTML pages.

The only other options I see are:

• Build the rest of the site with a static builder, and have that page render in the browser with JS. (bundle size might be big if it includes the dictionary as a package)
  • Not as accessible
  • But, doesn't require larger infrastructure on the server
• Use something like express to render the HTML for all requests for the site, more of a traditional MVC approach
  • Requires a little more setup and more hosting needs
• Use a SSR javascript framework like Next.js
  • Renders full HTML for users who don't have javascript
  • Users with JS will be able to browse the site as an SPA
  • But you're kind of stuck in the whole Next & React world

(there are other options/frameworks but these are the approaches I'm most familiar with)

I can think of one way to achieve it with static rendering, but it's a little hacky. Instead of rendering every combination:

• render a single HTML page that has every definition on it.
• put it at (for example) /my/_definitions.html
• have every request for a page at /my/something (/my/AsianAmerican+pan) show that document.
• use JS to parse the URL to get the terms, and hide all definitions that don't match.

But:

• you still need to use JS (might as well go with approach 1 above)
• pages won't have good SEO

from web-app.

(This conversation is getting out of my area of understanding, so can I entrust in you all to proceed?)

from web-app.

Hey,

sorry for being a bit quiet. Recovering from much life (recently) and a cold (currently).

Given the increasing amounts of contributions, I would prioritise creating an alpha build process that makes it easier for people to add content without the need for them to edit the index.html file.

I will try to open a PR with an implementation, tightly coupled to the expressed need of an open contribution flow in #12, over the next couple of days. Though this one will probably be easier for now and not yet easy, as easy takes time.

Building upon this we can iterate towards the full feature set for the compilation as well as refinement of the data structure itself. And maybe have a more focussed discussion step by step. :)

With warmth,
Oscar

from web-app.

Thank you, @ovlb! That sounds great. Step-by-step is helpful as this phase feels particularly auspicious and large.

My colleague suggested keeping word/definitions mostly as issues (creating a template, which I will do), and then limiting the number of PRs to just core contributors, which feels like a way to lower the barrier to entry and to keep the codebase tighter/cleaner.

Tagging in @lkopacz, who mentioned that she might be able to write some contributor documentation too! 💙

from web-app.

Thank you, Oscar! Your plan sounds perfectly prudent! Generally speaking even with most PRs, I'm hoping they can be handled by Markdown or other more common markup language.

The more I think about it, it's better if most of the true codebase is maintained by fewer individuals.

I had installed Eleventy and that is my preference, but understand if it's not possible.

from web-app.