Honestly, thanks... I'm about to start my first foray into blog-post writing, and I have a couple specific topics in mind. I had been debating whether I should start with the "background and motivation" section, or if I should just get to the point. Your article helped me decide that I should definitely just get to the point first. If the reader cares to go deeper into my specific motivation, then they can. But at the end of the day, the purpose of my post is to share knowledge - and soapboxing should be secondary.
My advice for just starting out is to not worry too much about following all the right practices. The more important thing is to try the process start to finish of picking a topic, writing a draft, editing it, publishing it, and finding places to share it. I'd start with something narrowly scoped that you can explain in 2,000 words or less.
I suspect that just experiencing the process end-to-end will give you a better sense of what areas you struggle with, and it will help you prioritize what writing advice to seek out.
This has been my experience in working with any kind of dogmatic structure or pattern in any language. It seems that the architecture astronauts have missed the point: making the code easier to understand for future developers without context, and provide some certainty that modifications behave as expected.
Here's an example of how things can go off the rails very quickly:
Rule 1: Functions should be short (no longer than 50 lines).
Rule 2: Public functions should be implemented with an interface (so they can be mocked).
Now as a developer who wants to follow the logic of the program, you have to constantly "go to definition" on function calls on interfaces, then "go to implementation" to find the behavior. This breaks your train of thought / flow state very quickly.
Now let's amp it up to another level of suck: replace the interface with a microservice API (gRPC). Now you have to tab between multiple completely different repos to follow the logic of the program. And when opening a new repo, which has its own architectural layers, you have to browse around just to find the implementation of the function you're looking for.
These aren't strawmen either... I've seen these patterns in place at multiple companies, and at this point I yearn for a 1000 line function with all of the behavior in 1 place.
Developer ergonomics is drastically underappreciated, even in modern times. Since we're talking about textual data formats, I'll go out on a limb here and say that I hate YAML. Double checking exactly how many spaces are present on each line is tedious. It manages to make a simple task like copy-pasting something from a different file (at a different indentation level) into an error-prone process. I'll take angle brackets any day.
You haven’t felt hate until you’ve counted spaces in your Helm templates in order to know what value to put after `nindent`. The punchline is that k8s doesn’t even speak yaml, the protocol is all json and it’s the tooling that inflicts yaml on us.
I can live with yaml as a config format, but once logic starts creeping in, give me anything else.
interrsting. I find the signal/noise ratio of XML really bad.
what I really dread in XML though is that XML only has idref/id standardized, and no path references. so without tool support you can't navigate to a reference target.
which turns XML into the "binary" format for GUI tools.
> so without tool support you can't navigate to a reference target
Maybe, but XML tools are also just superior to JSON counterparts. XPath is fantastic, and so is XSD and XSLT. I also quite like the integration with .NET.
My general experience with JSON as a configuration language has been sad. It's a step back from XML in a lot of ways.
> Developer ergonomics is drastically underappreciated, even in modern times.
When was the last time you had an editor that wouldn't just auto close the current tag with "</" ? I mean it's a god-send for knowing where you are at in large structure. You aren't scrolling to the top to find which tag you are in.
