-
-
Notifications
You must be signed in to change notification settings - Fork 11
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add deployment story for lecture series infra #38
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Really good write-up. I like the precise style of explanations a lot. Left a bunch of comments on cosmetics.
I have some general critique on the writing style:
- There are many side notes that break the reading flow. Consider including them in the sentences (I added some suggestions where it appeared obvious) or moving them to footnotes, if they really are not that important.
- Your sentences are often very long. I know this is how your train of thought goes, and it all makes sense. Yet, it's a cognitive burden on the reader who has to build up the stack to understand where you're going. Consider breaking up sentences now and then, and refactor them to avoid nesting.
- This is somewhat personal to me, but not using spaces around emdash (—) makes it really hard to discern insertions from word compositions. I always read "Project—tidily" and "infra—was", and that is just confusing. I know this is how long ago someone with a pointy hat decided to typeset American English, and it just makes me sad. It's such an arbitrary and counterproductive rule. In German you would use endash (–) with spaces around. I don't care which, we're on the internet and not in a 19th century book store, but please separate words with spaces. In general this still goes into the above point - consider using nested sentences sparingly, as they tend to break the reading flow and require the reader to build up stacks. Fragments are more suitable to be put in parentheses, but the same rule of frugality should apply.
@fricklerhandwerk Thank you so much for your excellent feedback. Your assistance here and with the Nix Ecosystem documentation is very confidence-inspiring. I’ll take another pass to address your notes, including more seamless integration of side notes and breaking up longer sentences. Regarding dashes: while em dashes without surrounding spaces for the use case in question are consensus among the academic style guides with which I’m most familiar, I acknowledge that SoN is funded by the European Commission and as such am willing to reconcile the discrepancy by observing the English Style Guide’s preference for en dashes surrounded by spaces. Incidentally, this corresponds to your favored punctuation from German, which for this blog I of course would be willing to accommodate even in the absence of an authoritative style guide. |
af8134a
to
b2d0554
Compare
|
||
_72 hours out. A bead of sweat slides from your brow, falls to the marred chassis of your local build server, and sizzles into mist, leaving a scant salt stain to tell the tale. It’s the start of the hottest Summer of Nix on record, and you have three days to [research](#phase-i-research), [provision](#phase-ii-provision), [configure](#phase-iii-configure), and [deploy](#phase-iv-deploy). With or without you, this lecture is going live._ | ||
|
||
The deadline was 19 July, 2022; at five o’clock on that glistening Tuesday afternoon, one Eelco Dolstra – a living legend to those who understand – would take to the webcam from the verdant city of Utrecht to deliver a highly anticipated slice of fresh perspective on his now-19-year-old brainchild, [Nix](https://nixos.org/learn.html). It was the inaugural event in the premier Summer of Nix (SoN) Public Lecture Series. The hype was real, but so was our predicament: no self-hosted livestreaming infrastructure was yet in place. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this a typo?
The deadline was 19 July, 2022; at five o’clock on that glistening Tuesday afternoon, one Eelco Dolstra – a living legend to those who understand – would take to the webcam from the verdant city of Utrecht to deliver a highly anticipated slice of fresh perspective on his now-19-year-old brainchild, [Nix](https://nixos.org/learn.html). It was the inaugural event in the premier Summer of Nix (SoN) Public Lecture Series. The hype was real, but so was our predicament: no self-hosted livestreaming infrastructure was yet in place. | |
The deadline was 19 July, 2022; at five o’clock on that glistening Tuesday afternoon, one Eelco Dolstra – a living legend to those who understand – would talk to the webcam from the verdant city of Utrecht to deliver a highly anticipated slice of fresh perspective on his now-19-year-old brainchild, [Nix](https://nixos.org/learn.html). It was the inaugural event in the premier Summer of Nix (SoN) Public Lecture Series. The hype was real, but so was our predicament: no self-hosted livestreaming infrastructure was yet in place. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
“Take to the [platform/medium]" is an expression, where platform/medium can be practically anything (e.g., stage, podium, mic, pen, quill). It’s a bit of literary flair to complement the energetic tone of the paragraph.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Okay, please don't use idioms in technical writing. Most people who may be able to read your article (1.5 B) don't know enough idiomatic English to make sense of them. (Sample size 1: 20 years of exposure and 10 years of daily English practice is apparently not enough in this case.)
Possibly self-explanatory idioms are fine. See controlling the narrative vs. framing the discourse.
b2d0554
to
232445f
Compare
@ctem @fricklerhandwerk is this ready? |
This is one SoN participant’s humble retelling of the legend of the 2022 infra project—the birth of an era.
Note: while the document itself is ready for review, the way the site renders it is a little wonky at this point:- Markdown isn’t supported in titles
- inline code blocks and tables render with no backgrounds or borders
- cramped whitespace between sections presents a risk to structural clarity
(Rendering issues addressed in #39.)