Binyamin Green - Microblog

What information do you include in the README of a web project?

Thu, 16 Mar 2023 23:15:55 GMT

On Mastodon, Matthias Ott asked, What information do you include in the README of a web project? Any great examples you can think of? Do you use a template? Or do you write them from scratch every single time? I started drafting a reply, which broke Mastodon's character limit. So, now it's a blog post.

Anyhow, the structure of a readme often depends on the project, but there are some common points.

At the top of the readme, describe the purpose of the project. Be stupidly simple. State the obvious.
If the readme is for a website, link to the live website. It's surprising how often people miss this part.
If the readme is for a library, document the API. Nothing complicated, just a bullet-list with some code examples. Typescript definitions (typedefs) don't count. And while code should be self-documenting, it doesn't need to be the only form of documentation.
It's often helpful to link to related projects. You give those projects the boost they need, and your users can make an informed decision about your project.
Maintenance info: Is this just a personal project, or are you looking for actively looking for pull requests? Can people expect a quick response to their issues, comments, and pull requests? We're all busy, so there's no judgement here.
For legal reasons, I always include a short note mentioning the license.

That's my two cents. I also wrote another shorter note about this topic. So that's like, 3 cents. Which is very cheap, in case you wanted to buy me a coffee.

The Seductive Simplicity of CSS

Fri, 23 Dec 2022 00:18:36 GMT

I found this quote back in September.

CSS is a programming language. As unintuitive as it might feel to you at times, it's not just these random things that happen. It's built using very specific rules. The problem is that most people never learn those rules.

We start learning CSS by learning the syntax, which is super simple. That tricks us into thinking that it's a simple language.

Don't let the simple syntax trick you. Dive into it and learn how it works.

— Kevin Powell, Software Engineer & CSS Educator

Is GitHub's UI too friendly?

Thu, 12 Aug 2021 01:22:24 GMT

People have come to expect a repository's source code to guide them through the contribution process. That job belongs to documentation and developer guides.

Comments are for the people writing the code, not necessarily the peanut gallery. If a readme was meant as a sales pitch, it would be a website or a blog post.

On Sadness and Happiness

Sun, 13 Jun 2021 20:45:25 GMT

Sadness. It surrounds our thoughts and emotions. We want to the believe this emotion doesn't exist, let alone affect us. But it's always there. It watches from the rafters, and it pulls us elsewhere – not exactly down, and not upwards either. Sadness is a cat, and we are mice. And happiness is the mousetrap.

Happiness is the delusion of perfection. What we truly seek is balance. Balance keeps your ice cream cone from falling apart again. It cannot remove the scrape from your knee, but it can give you a bandage. A kiss goodnight will not scare away any monsters, and still your bed will become safe for sleeping. You will have learned nothing, because you have plenty of wisdom already.

Let yourself grow taller. Plants need water and sunlight, but you are not a plant. Only fools set limits; the wise use guidelines. Run down the trail, even as you stay on the path. When the road splits, go left. Or right, it makes no difference. Momentum is a precious thing, and choices are all too common.

Advice on giving feedback

Fri, 11 Jun 2021 20:43:27 GMT

I was looking at some posts from my RSS feed, and a piece by Ethan Marcotte caught my eye. It helps to know that people still value kindness.

Is there a piece of professional or life advice you’ve gotten that has always stuck with you? What is it?

My grandmother once told me, “You should offer praise in public, and offer gentle criticism in private.” She said a lot that shaped the way I approach the world, but I think about that particular suggestion a lot.

— Ethan Marcotte, in “Bookiversary”

[A clever phrase]

Thu, 27 May 2021 20:31:55 GMT

Here, I subtly introduce you to the topic at hand, and grab your attention. I may use fantastic words and extravagant linguistics, or I can just be really boring and stuff. That's called an introduction. Use it.

Now, I start to get into the nitty-gritty of the article. I may include some cool things like {% liquid:tags %} or inline code.

document.before('codeBlock', () => {
  do("explain with words");
})

Now, I write another paragraph. Write at least two body paragraphs, with at least three sentences each. Use proper grammar, ~~ppl~~ people!

Lastly, I leave you with a thought which will remind you of what I've written. It's called a conclusion, and it's like a party favor or gift. It leaves the reader with a good impression. Think of it as a nice way of saying, goodbye.

I shaved 65 kilobytes off my site

Thu, 18 Mar 2021 00:53:47 GMT

I saved 65 KB on this site. Basically, I removed two web-fonts and cut out some CSS. Overall, I went from 93.8 KB to 28.8 KB.

I rewrote my styles using vanilla CSS. Originally, I was using a SCSS because of its nesting capability. Another benefit of SCSS is that you can split your styles among multiple files. By default, CSS doesn't perform well in that respect^[1]. An advantage of using CSS, was that it forced me to write my styles more succinctly. By limiting myself to one file, I gave myself a practical reason to keep the file size to a minimum.

I also started loading fewer web-fonts. I removed the body and display web-fonts, opting for local fonts instead. I was using Roboto (sans-serif) for the body text, and Lora (serif) for the headings. I switched them both to a single, local-only, "catch-all" font stack. I can hardly tell the difference.

Otherwise, I made minimal changes to the website's visual design. In the process of rewriting the CSS, I made some stylistic decisions. For example, I changed the theme of my code blocks from "Nord" (a dark theme) to "GitHub Light". I also removed the CSS reset I was using, which was normalize.css by Nicolas Gallagher.

Size Comparison *
	Before	After
Roboto font	15.4 KB	0
Lora font	34.5 KB	0
Google Fonts CSS **	11.4 KB	2.4 KB
Normalize & code-block theme **	4.2 KB	854 B
Sitewide CSS **	5.4 KB	3.4 KB
Print CSS	801 B	748 B

* GTmetrix reports: before, after
** Uncompressed size

Oh, and the best part is... my site is now only 100 ms faster. 326% smaller, 8.3% faster. Go figure. 🤷‍♂️

Think about it. Every time you request a CSS file, whether using a <link/> tag or @include syntax, you make a network request. As every network request has a cost, it's much more practical to combine your CSS into one file. ↩︎

Doubting full-post RSS feeds

Mon, 11 Jan 2021 15:17:13 GMT

I read a post by Kev Quirk championing full-post RSS feeds.

I'm trying to think of ways to encourage people who use my RSS feed (if they exist 😉) to actually read the articles on my website.

Why? I work hard on my website.

I try to be accessible at all times
I aim for the optimal reading experience
I design for aesthetics as well as simplicity

Mainly, though, my website represents me. It's the only coding project I've worked on steadily for the past three years. It's been painstakingly redesigned multiple times, and I try to put flair and charm into each iteration. I care deeply about my website.

If you have any suggestions, please let me know.

Reorganizing my website

Tue, 29 Dec 2020 22:11:45 GMT

URIs don't change: people change them. That's what Tim Berners-Lee says, either way. I was reading his article "Cool URIs don't change", and I started thinking about my own website. I recently implemented a micro blog, and it's possible that I will want more kinds of posts in the future.

That's the answer, I realized! They're all posts, each with a different category. I decided to construct these categories using the Indieweb's concept of a post type. I just need a blog and a micro blog (indieweb: articles and notes), and I should have room for other posts like photos and book reviews.

So, I changed my URL structure. Static pages, such as contact and now, stay the same. If it's a post, it'll be under /p/{title}/. Lastly, each post had a category page like /blog/. Under this new system, that'll be /c/{category}/.

Okay, that's a wrap on this article. Oh, one more thing. I set up redirects for my old posts. That's all. Thanks for reading!

Your Turn to Yell

Tue, 15 Dec 2020 02:05:08 GMT

“Silence is Golden”, they say. They're right, of course. Silence is the key to every problem, as well as to every proposed solution. Arguing won't solve problems; not directly, anyhow. So what will? Listen, you say. And you yell, a long, painful moan. I sit, and you scream. I listen while you lament. It's a powerful dynamic, this. I learn your hardships, and you- well, I don't know what you do, but it's dramatic. You shout, and I sympathize. You accuse, and I admit. Is it my turn yet?

Finally, you come to the end of your conversation. A question burns in my belly, though I dare not ask it. You leave, and take with you a bundle of anger. I leave too, adding yours to my collection. May I talk now? No, not yet. You see, to talk I need a listener. My door is open; you may vent any time you please. Perhaps, one day, you will open yours.