Skip to content
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

Merged
merged 1 commit into from
Sep 6, 2022

Conversation

ctem
Copy link
Contributor

@ctem ctem commented Aug 16, 2022

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.)

Copy link
Collaborator

@fricklerhandwerk fricklerhandwerk left a 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.

@ctem
Copy link
Contributor Author

ctem commented Aug 20, 2022

@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.


_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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a typo?

Suggested change
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.

Copy link
Contributor Author

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.

Copy link
Collaborator

@fricklerhandwerk fricklerhandwerk Sep 1, 2022

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.

@MMesch
Copy link
Collaborator

MMesch commented Sep 6, 2022

@ctem @fricklerhandwerk is this ready?

@fricklerhandwerk fricklerhandwerk merged commit 5c2455e into NixOS:main Sep 6, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants