Majorly improve article
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful

This commit is contained in:
Isaac Mills 2024-04-07 22:46:36 -04:00
parent a84ee403c2
commit 3d052bc03b
Signed by: fnmain
GPG key ID: B67D7410F33A0F61

View file

@ -37,7 +37,7 @@ Pictured above is the full pipeline that articles go through in order to reach y
4. Once the article has been edited, the pull request gets merged into the main branch of our git repository, which is where the articles you see live
5. From there, the article goes through CI and gets deployed (we'll get into that in more detail later)
Basically, this is just the workflow you would use for code, but adapted for journalism. In other words, no learning curve for our journalists! And if they do need to learn it, then this is information that they *should* know _anyway_. The workflow you see above has been in the making since git was created in 2005, with the sole purpose of efficiently moving code from development, into production. The more efficiently we can accomplish that, and the more bad code we can filter out of production, the better. If this workflow has worked for nearly 2 decades for a pathologically huge project like the Linux kernel (which git was tailor-made to handle), the better.
Basically, this is just the workflow you would use for code, but adapted for journalism. In other words, no learning curve for our journalists! And if they do need to learn it, then this is information that they *should* know _anyway_. The workflow you see above has been in the making since git was created in 2005, with the sole purpose of efficiently moving code from development, into production. In the places where this workflow is used, more overhead in the pipeline means time, and time means money. Thus the workflow used in those places should be as simple as possible to reduce overhead, and I see it no differently for our publication. If this workflow has worked for nearly 2 decades for a pathologically huge project like the Linux kernel (which git was tailor-made to handle), the better.
## CI
@ -45,9 +45,9 @@ Consider the following: If I'm accepting untrusted code from the public into my
Their pipeline checks if the library with your new code compiles to every platform it's compatible with, with every feature enabled. It also makes sure that your code is well-formatted, contains no conflicts of license, uses no libraries banned by the project, and contains no security advisories. The _only_ way this many checks can be done on every git commit, is through CI, GitHub Actions in egui's case.
If you're making an open source project, and it becomes big enough to pull in contributions from a lot of developers, CI can not only serve as a means to filter bugs out of pull requests, but also as a way to communicate to open source developers _what a project wants_ out of their code. Instead of having to read a big `CONTRIBUTORS.md` file to get an idea of that, developers can know that their code is good quality if it just passes CI.
The way I've described CI so far has probably made it seem like the least simplest thing you could add to your project, but CI is actually _quite_ simple, and it's an excellent example of how capable of a tool you can make by just building simple, on top of simple, on top of simple. Really, CI is just shell scripting with extra steps. Despite it's inherent simplicity, CI can not only serve as a means to filter bugs out of pull requests, but it can also be a simple way to communicate to open source developers _what a project wants_ out of their code. Instead of having to read a big `CONTRIBUTORS.md` file to get an idea of that, developers can know that their code is good quality if it just passes CI.
Fortunately, the level of CI I've described above is not required for journalism. Our CI simply compiles our journalists' unreviewed articles, and serves them on an un-indexed (not visible on production) web page so that they and the team can preview their work before merging it. Our CI is also responsible for indexing and publishing finished articles onto our production website. We could get the CI to do an automated grammar check, but there are too many tech-terms that the checker would need to know in order for it to pass consistently.
Fortunately, the level of CI I've described above isn't required for journalism. Our CI simply compiles our journalists' unreviewed articles, and serves them on an un-indexed (not visible on production) web page so that they and the team can preview their work before merging it. Our CI is also responsible for indexing and publishing finished articles onto our production website.
## Deployment
@ -63,20 +63,24 @@ Because our CI tool is running this code, we can know which articles need compil
- Run a blame on new articles, which is how we figure out who wrote them
- See if we are we have changed the production branch, and index new articles if so
In our case, what CI allows us to do is keep as much of our pipeline as automated as possible. Our journalists should only need to focus on writing good articles, not wrestling with tooling. Coming back to the benefits of plain text, git is an extremely powerful tool for working with plain text.
Everything I've just described can be done in just ~400 lines of Rust. This is the effect of buidling simple on top of simple, _and making an effort to retain simplicity_ by making the most out of the simple building blocks.
![Google cosplay is not business-critical](https://programming.dev/pictrs/image/e69b09e9-3ef6-40ff-b47b-e2ba2b4b633a.png)
My Rust code makes heavy use of git, a very simple yet amazing tool for adding functionality to plain text.
- It allows us to separate the WIP and the finished articles
- It allows us to keep an accurate and automated reference of who wrote and edited each article
- It allows a copy of the entire publication to be stored in many different places as backups.
- It allows us to easily sync new articles and changes to any git-compatible software forge of our choice (we use [forgejo](https://forgejo.org/))
By and large, with the power of git, plain text can fill more use cases than you could possibly imagine.
By taking advantage of the vast functionality that a simple tool like git gives us, our code can stay lean, while also being very mean. Speaking of staying lean...
## Our webpages (and staying based)
## Webpages (and staying based)
![An image of the giga-chad](assets/giga_chad.jpg)
The modern web sucks. Most webpages are not only bloated with ads, cookie banners, autoplaying BS, popups and the like; most webpages are also inundated with copious amounts of JavaScript. We only use JavaScript in 2 places
There is no better example of the cons of complexity than the modern web. Most webpages are not only bloated with ads, cookie banners, autoplaying BS, popups and the like; but they are also inundated with copious amounts of JavaScript. We only use JavaScript in 2 places
1. On our homepage to power the search bar and display articles
2. Our web design tool, Webflow, bundles a small amount of JavaScript in every page (more on that later)
@ -85,10 +89,8 @@ Other than that, the actual article pages, such as this one, depend on nothing b
Instead of _that_, I used [Webflow](https://webflow.com/) to design our webpages. For a one-time fee of $24, you can have access to the Webflow editor for 1 month, and then export your web pages to HTML/CSS/JS. Webflow is very different from your average Wix/Squarespace, those editors are designed for non-programmers who don't know and don't want to know HTML or CSS. Webflow is an editor for _developers_ that know what they're doing. It gives you the full power of HTML and CSS in a responsive, visual editor; making it an incredibly flexible tool capable of generating very based and performant webpages. Unlike the latter tools which generate bloated and obfuscated garbage.
## Search engine
I was expecting to have to put most of the effort of getting our website ready into getting a search bar working. Instead, I found [Meilisearch](https://www.meilisearch.com/), and I fell in love immediately. Not only is it incredibly easy to deploy _and_ use, but it's also much more than just a search engine. You can basically use it as a way to index and display pages on your website. And by using [instantsearch-meilisearch](https://github.com/meilisearch/meilisearch-js-plugins/tree/main/packages/instant-meilisearch) (that one dependency that our homepage uses), we can just make an article browser and search experience, _incredibly_ easily. It's not just easy on the front-end, the [meilisearch-sdk](https://lib.rs/crates/meilisearch-sdk) is also incredibly easy to use to index articles. Meilisearch, despite being a complex full-text search engine, is incredibly simple to use. Just initialize a search index, and send documents to it in a structured JSON format. On the front end, you can get that JSON back with a simple HTTP request containing the search query and field constraints (sorting, only sending snippets of big fields, etc.). All in all, Meilisearch's unexpected simplicity suprised me in a big way, and it made my job so _sooo_ much easier!
In just HTML, CSS, and JS: The homepage of this journal compressed is around 152.42 KB large, whereas our old Wix website's homepage compressed is around 861.9 KB large. That's nearly a 6x size difference. That's the effect of building your website in a UI that attempts to match up to the flexibility of HTML and CSS... without actually exposing you to the HTML and CSS. This is where Webflow thrives, as it is literally just a simple graphical editor _for_ HTML and CSS. It's another excellent example of what building simple around simple can do!
## In conclusion
Computers have an inconcievable amount of potential, but they're only as smart as their programmer. When you're building something with a computer, it's often much better to do more with less, than less with more. Don't use 17 different JavaScript frameworks with your hypervisor GPU WEB2.0 interface-driven scripting framework to drive your map/reduce-aware proxy-oriented software API. Just start simple, build simple, and if you need complexity, build it with more simple. Often times in computer software, plain text is the simplest place to start. From there, you can add complexity by processing the plain text in some way (hell, I made a whole ass [PowerPoint clone](https://github.com/StratusFearMe21/grezi-next) centered around plain text). If you need more than plain text, try the terminal. And if you need more than that, try [wxWidgets](https://www.wxwidgets.org/). The point I'm trying to make here is that bloat is your enemy, and it's often better for you, your team, and your users to just KISS (Keep it simple, stupid!)
Computers have an inconcievable amount of potential, but they're only as smart as their programmer. When you're building something with a computer, it's often much better to do more with less, than less with more. Don't use 17 different JavaScript frameworks with your hypervisor GPU WEB2.0 interface-driven scripting framework to drive your map/reduce-aware proxy-oriented software API. Just start simple, build simple, and if you need complexity, build it with more simple. The point I'm trying to make here is that bloat is your enemy, and it's often better for you, your team, and your users to just KISS (Keep it simple, stupid!)