We called this the “receptionist” test decades ago at the small company I was at - after we though we were done we’d give it all to the receptionist and ask her to use it; and we’d hang our head in shame at everything we forgot and head back.

There’s a version for kids to show the details of how to program by literally interpreting steps. https://youtube.com/watch?v=n4rh2jD8OkY

I seem to have this problem a lot with Apple’s docs. So much of it is like

    Nargflargler: Flargles the narg

You need to do something besides repeat the name in the definition.

> Do not speak to them, certainly do not help, just watch.

Sounds simple, right?

I ran usability tests at a past company and have seen people who were incapable of blurting out explanations, pointing at the screen, even audibly grunting or whining to themselves when the participant made an incorrect guess about what something meant. One even grabbed the mouse.

Having a neutral moderator can help as it allows the people who made the UI/docs to stay on mute or on the other side of one-way mirror.

But I'd still suggest learning the "just watch" technique. If you master that and wish to take the next step, look up "think-aloud protocol".

This is our documentation workflow as well: Write it, and then have someone less or not experienced with the system execute the runbook. Also, encourage everyone to work on refining and improving the docs, because after 5 years with a system, I will have blind spots someone less experienced can point out.

On lesson I've learned from that: It's a lot about managing confidence of the user.

To do this, the instruction of "invoke this shell command" is now usually accompanied with a number of sections collapsed by default: How does a successful invocation look like - especially if it contains "ignorable warnings"? What errors could occur, and are they fatal or can they be fixed on the fly? Some more complex shell-stuff is often also accompanied by an explanation of what all of this is.

And yes, this means that sometimes one step in a runbook has a page of documentation if you read it all. But we've found that this helps a lot during onboarding new team members, as by now, a lot of the standard runbooks are also a prety good introduction to the quirks and quarrels of the normal tools we use.

Any kind of documentation has a target audience. Your test is very valuable if and only if the target audience is a total beginner. Of course it's still very hard to write good documentation even if you have identified your target, but having someone totally illiterate on the subject matter review your documentation is as useful as if I'd have to review a PhD thesis in quantum physics. It just doesn't make sense (trust me :).

Writing documentation is hard. Start with: Who am I writing this for?

edit: I may have misunderstood OP's "with minimal expertise" for "total beginner". They're two different things, absolutely.

It's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be. The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end up writing up a new doc that's good for its point in time, immediately becomes out of date when someone adds a new system or access group but doesn't document it anywhere. The one team I was on previously that got me everything I needed in about two days was great, but it's sad that this isn't the norm. Everywhere else has been pretty hostile to getting set up, and the poor onboarding experience has been a preview of the developer experience. My current role is standing up a new devex team which I'm hoping turns the tide here.

Reading through bad setup docs is 10x more stressful when they are part of new employee onboarding.

I’ve always advocated for new employees first contributions to be fixing problems they had in these setup materials. They are coming in with fresh eyes and no context so they are the best possible reviewer

I worked with someone who was great with this. They’d go through the docs and do exactly what was said, document where problems were hit and then repeat from scratch again and again. Seemed slow but their docs were excellent and I’m sure it saved more time having him hit each thing once than everyone else hitting them loads.

You can achieve a lot of this by creating a blank virtual machine with "just the operating system" as a starting point and stepping through your own instructions from there.

My ideal state is that for my kind of .NET work, it should be sufficient to simply install the latest Visual Studio, check out the Git repo, and press "play".

That's not always possible, so then the exercise becomes to simply document each step, ideally with both English words and a CLI snippet.

Or let the Junior rewrite the docs while they're scratching their head, and push an update once they've figured it out.

Apple documentation reminds me of an argument I got in with an elementary school teacher over a textbook… it went on for weeks

> A prepositional phrase is a phrase with a preposition in it.

> A preposition is a word in a prepositional phrase.

Triangle theTriangle = new Triangle()

Lives rent free in my brain.

A good first exercise for new hires! (And I say that as having been both a new hire who's updated the documentation after trying to execute it, and as someone who's guided a new hire when the documentation proved inadequate.)

I was gonna write something similar. Know the audience. I've also come to the conclusion that "total beginners" (and certainly "minimal expertisers") didn't nowhere to read the docs anyway so it didn't matter.

In other words, people who are used to reading docs can read (good) docs just fine.

Yes, of course, good docs are a must. They are critical to success. But not all docs have to explain how to use a right-mouse button.

The experts are likely to be skimming and interpolating your doc, so they'll get through it but you won't know why. You won't know if your doc works, or if it even addresses the subject matter. This is also true of academic papers.

My mom taught CS in the 1980s, and told her students on day one: "Computers are stupid, they will only do exactly what you tell them to do, not what you want them to do." Program code is, in a sense, a tutorial for an utter beginner. The benefit of coding is that you can do the "beginner test" over and over without wasting anybody's time, so you know that the computer will get through it. But an expert (including yourself) might read that code and never see that it does or doesn't work.

A technical writer's first task is to start the document that onboards the next technical writer.

My first ever software developer job, I was hired with basically no knowledge or experience to learn (I was very lucky). I knew MS-DOS command line pretty well from my childhood, but hadn't ever used POSIX. I was given a macbook air and some docs to follow.

Trying to follow the docs, supplementing with a lot of googling, I somehow managed to remove the tar program from my system. This broke literally everything. Had to stop halfway through the multi-day process to do a clean reset and start over from scratch.

I agree that testing from a vanilla machine is important.

But there's also that your language to the user doesn't necessarily say what you think it does. You can't read it from the position of someone new. Only someone new can.

And a set of commands to paste to CLI isn't the full extent of what we usually mean by documentation.

Indeed, snapshots are an amazing friend for this.

I echo this sentiment. Whilst I completely understand that developers are doing this in their own time and largely for no other reason than it being a labour of love, it would really help lower the barrier to entry.

Oftentimes when the tool is typically used as part of a useful stack, the other components have documentation that can also be difficult to decode. So it becomes an order of magnitude more difficult to understand.

What I really really want to read in a README is *why* did you build this? The "rationale" section of a README is almost always the most interesting part.

I can read the code, I can understand how it works but I cannot know why you decided to tackle this issue a certain way.

There was a project posted here once that didn't even bother saying what the thing even was!

OpenGL is not so bad because the API is quite stable. WebGL in particular is great because there's literally zero setup you need to do for executing it.

Integrating with Linux/Windows display surfaces is disgusting however. KMSDRM is way, way better than the nightmare that is X11 and Wayland.

I want a linter against this. I have a hatred for those kinds of docs, they take up screen space, its worse than nothing.

AVMetadataKeySpace

A structure that defines a metadata key space.

source: https://developer.apple.com/documentation/avfoundation/avmet...

This is just one example of how metrics can distort things, of course. Someone in management said "We want 100% documentation coverage of every method," so the staff dutifully wasted everyone's time by writing "setDefaultOptions: sets the default options". It's the kind of thing an LLM could have done better, and if you know my opinion of LLM's, you'll know that's damning with faint praise.

My own bete noire here is MSDN. It's full of overloads like "Foo(string parameter, FooOptions options) - actually useful documentation. Foo(string parameter) - does Foo with default options." But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are. (A few pages are better, thankfully).

Related to this is the omitting of units. I encountered something like this in the Android SDK (years ago, dunno if it’s still like this).

    setFontSize(float): sets the font size.

Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I expect for fonts (points).

Not quite what you're talking about but this Apple doc page has always amused me: https://developer.apple.com/documentation/contacts/cnlabelco...

I have to assume that there exists some language where that relationship is described in one word, but it hurts my English-oriented brain.

Or with Xcode, go to fargler settings click on narg screen. Took a year just to figure out most setting screens

One problem I remember from (briefly, fortunately) dealing with Apple APIs is wondering incessantly why every API (I was looking at) started with NS. Admittedly these days any AI would tell me it stands for Next Step. But if you are creating a new thing with a quirk like this please explain it once, in a place that's easy for the student to find.

I mean, if the test user can't figure it out at all, how is the rest of the UI/documentation supposed to get evaluated?

> You can also record it to show them later, but for various reasons it doesn't resonate quite as strongly when it's not live.

Yeah, because it's wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts. It's fine if I actually have the time to explain to some Gen Z kid how Ctrl+X/C/V works, but being forced to sit around and watch someone with that level of non-understanding of how a computer works when I got a full backlog of shit to do is just agonizing.

With a video recording, I can at least go forward and see where they actually have problems with stuff that is in my influence and skip over the utterly boring moments that are just wasting my already limited time.

For most public documentation, you don't get to pick your audience. You think you'll have people with certain experience, but then it turns out you're wrong. Usually a lot of the time. And even when you're not wrong, having the steps essentially from scratch listed out reduces the number of times people get stuck, because they think about things they may have missed.

Perhaps in addition to a description of the expected audience, it might be an idea to list some assumptions made about the reader? e.g. has installed software previously, confident with bash commands, &c

It's not very crazy to me. Most corporate teams are overrun with feature creep that "is very simple" (i.e. it takes 3x as long as estimated, because the codebase is a mixture of overengineered spaghetti for that one customer with edge-case requirements and legacy, combined with tests that are meant to be run in a jenkins job which takes 4h to complete).

Then, the engineers are expected to write the docs in between these tickets, and doc is seen as something "to be done within 30 minutes" - of course the docs will be comically (or tragically, depending on your perspective) bad.

Most people have 0 idea on how to write good docs, so in 30 minutes, they write stream-of-consciousness docs and return back to the ticket hell.

if you're writing a new doc to "fix" this situation, you're commiting three crimes: 1. all that old documentation still exists, misleading and confusing people. you've now made the problem n+1, 2. there's no strategy to keep your new document from turning into an old, stale & out-of-date document for the next person, 3. you've addressed the wrong problem (nothing's documented!) and feel like you're superior to all the jerks who came before you.

>> My current role is standing up a new devex team which I'm hoping turns the tide here.

I'd love to know what you're doing different that can help with this problem. Writing more, new documentation is unlikely to be it.

Sometimes I wonder if it's a respect or control issue. I once worked in a non-technical position that interfaced with a complex order management system. We were given zero access to documentation and had to rely on trial-and-error and the reverse-engineered model held in the head of one specific supervisor. I'm almost certain that certain errors that appeared over and over were caused by us temporarily clearing previous ones incorrectly. This was especially frustrating because we were 2nd shift, so dealing with those errors could mean the difference between getting home that night or getting home the next morning. It was hard to tell where along the line between, "They're not sophisticated enough to make use of them," and, "We don't want our processes leaking," we fell, according to the higher ups.

I am that guy. I will also say from experience: It does not pay. Never once has it been ack'ed in a year end review (which controls bonus, salary increase, and promotions). As soon as a manager sees you as "The Wiki Guy", they take you for granted. As I grow older and more cynical, my view on internal docs: (1) Write them for yourself. (2) Write them to make people go away when they ask you questions ("Did you search the Wiki?").

Funny enough, we had a hell of a time running a helpdesk where we designed the docs -- many of which I wrote myself -- to be executed exactly as written.

Guess what humans hate to do? Especially the smart ones, which of course you want to employ on your helpdesk? They just would not read the damned instructions.

I think this was because many of the instructions were dumb. We were explaining decades-old bank stuff. It didn't make sense, but it's what you had to do! So these guys tried to 'fix' it, and in doing so, broke it.

The whole support model was predicated on this idea that the 3rd level guys would write stuff that the 1st level guys would slavishly follow. It never worked.

Yes, more of this!

I am a big fan of the "clone, F5" and it should run. If specific steps are required, I put that in a setup.ps1, and the details in the readme.md.

If the project has external requirements, I put a link to the repos, which should all be... "clone, F5"...

"Most tutorials are not for non-developers"

That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers.

Like some open source Github project that the author merely wanted to install, not starting to mess with the code. Basically, it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps. A complaint that I can very much agree with, even though I am a developer. But so often little steps are left out and when that happens in a area you are not familiar with, then this can mean lots of wasted hours.

> Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem.

To me eye, most tutorial nowadays are so a developer can put "made public contribution to <X>" on their resume or quarterly evaluation rather than helping other developers.

I'd be even happier if the original writer would simply come back 3 months later and retrace their own directions. That would make the tutorial vastly better as they will suddenly see all the little things they left out.

This issue with READMEs in particular has driven me nuts for the decade I've been doing ROS related robotics stuff. So many repos where the only surface clue (i.e. before diving into the code) of what it does is your interpretation of its name.

But I'm pretty sure it's universal, like you allude to. And not just open-source; but at work, too. I feel like I'm the only one in my company that makes PRs to edit the READMEs to explain what a repo is for, and what repos it might relate to. (I was much happier in the past when we had a couple mono-repos; now the trend is every little project gets its own undocumented repo, alas.)

I have encountered a number of people who exhibit startling hostility at being told something they were already aware of. While I cannot currently recall a specific example, I strongly suspect I have previously felt this way myself.

While sharing may be better than assuming when only considering the local optimum, if your signal to noise ratio is bad enough, you will face an impairment to communication that simply wouldn't exist if you had been more selective.

> If they do know, and you tell them, then you've only really confirmed what they already knew.

Not necessarily. This opens you up to accusations of engaging in "mansplaining" which has broadened in definition over the years.

In addition to this, it opens you up to being thought of as a "know it all".

It's far safer, as far as office politics are concerned, to put on your coworkers the burden of asking you to clarify/explain/teach.

The main advantage of cmake is it's slightly easier to use than autoconf so long as you stick to the path. Do not attempt to leave the path. Also the path is poorly signposted.

FWIW, I was one of your users - back when it seemed important to jailbreak my iPhone - and I appreciate the work you put into it. I'm guessing that it was pretty thankless, for the most part.

Brilliant to see something from you here - a long time ago, I was there as well using your products and making a mess of things with stuff like afc2add and iPhoneBrowser

Yeah, this poor guy stumbling around the internet who should be reading kids books keeps clicking on kubernetes how-tos

> Beginners have to be nurtured through lots of context that builds up slowly.

My son is 17 and very interested in programming. Had to explain to him public, private, internal, and also static the other night.

I then joked, you should ask your teacher about recursion tomorrow. He's with his mom this weekend, but I'm anxiously awaiting hearing how that went.

I've been coding in C++ since the 90s, that's also how I feel whenever I'm required to build something using cmake.

This is hilarious to me, because for me it is exactly the other way around.

Just last Friday, some coworker showed me her mermaid diagrams about workflows at work. I am still not comfortable with needing to login to some website to convert some format into a useful format. If I cannot run it locally on my computer it doesn't exist for me. So I tried to install their official looking cli client.

The protocol from my memory roughly looks like this I npm install something, then it tells me I have to npx (wth is that? I think that is new) install something, which gives me some weird puppeteer permissions issue. If it is permissions I guess I have to be root for the install, I try a bit more and get nowhere the same issues keep happening. Look on their website, see they have a docker as an alternative, this is a pretty newly installed computer so I have to install docker, but which one? There is 3 options and I am not sure. I try to run their docker and mess up because I do not read the documentation correctly and I have to map the directory with my .mdd file with <my-dir>:/data and this was unintuitive to me so I ignored the first part and replaced /data with my path. Again obviously a mistake on my side, but it happens every time and adds to my confusion. I look into the docs again and find my mistake. I finally get a resulting svg from the docker command. Excitement! I open the svg and it lacks all the text and I think there were also errors in the shape. Then I remember obsidian has a mermaid plugin so I thought about trying that, but the obsidian install also fails with some random error about not being able to connect to chrome.

On the other hand whenever I get a cmake project I clone it. I create a folder for the build, cd into it, run cmake <path-to-source-folder> without even looking at the documentation and it either works or I get a pretty clear message what is missing on my OS and with a short web search I can just apt install it and try again (yes this sometimes has multiple rounds) and it works!

It's easy to blame Hoobastank, but in my experience with these issues, most of the time the reason is you.

So sorry about that. I should have mentioned the DNS resolver as a potential issue because it’s always DNS. Terrible oversight on my part, probably because I am not a developer.

In some fairness, the page existing at all is half the battle. I'm glad the canvas exists for the paint to eventually, maybe, one day arrive.

In similar cases (maybe not exactly here), I suspect the author also didn't know and didn't care to look it up and just wanted to tick the box that it's now documented.

> with Xcode, go to fargler settings click on narg screen

I hate how this looks "accessible" to people in theory, but in reality finding those screens is more like playing a hidden object game.

Also, I hate how those things keep changing around in all kinds of software, but especially Apple. Somebody probably thinks "yeah maybe we should move the Fargler settings from the Narg to the Birp screen", and makes dozens of internet "documentation" (and sometimes their own!) obsolete.

I almost systematically use BLUF (Bottom Line Up-front) when I write docs, I think I'll make TABLUF a thing from now on (Target Audience and Bottom Line Upfront) :)

Most places I've been could have been upgraded with stream of consciousness. It's not surprising that they aren't all perfect, and the one place that was done to a very high standard was properly overdone, but at most places whatever counts as onboarding docs either doesn't exist, is essentially unusable, or directs me to legacy things that on day one I don't know enough to not bother with

You're right that it's not a complete solution. The overall process on this team aren't good (we never do a retrospective, ever) and I don't get to decide how we solve #2 and #3. The best I can do is bring things up to date, keep it up to date as I run into new info or we add new systems to access, and hope that future new hires are smart enough to check created and last modified dates on documents to find the most recent one.

My mother worked in engineering back in the late 80s until early 2000s and always told me about people who didn't document things because they wanted to be un-fireable. I didn't believe her or take it too seriously until some of these more recent teams, but I think it is a lot more common than it should be.

I had this issue during a job interview exercise. Their "follow these steps exactly" were simply broken. The root cause was that they were having people re-use the same shared remote amazon desktop system. Each candidate got their own home directory, but they wouldn't just reset the image between candidates. The person before me had used up 98% of the drive space. When I followed the 'step by step' guide, nothing worked, because it was out of drive space, but... I wasn't seeing 'out of drive space' messages directly - I was seeing their 'setup shell scripts' looking like they worked, but then nothing did.

I honestly thought this was some sort of trick exercise to see how I deal with broken processes, and I was writing fixes to their docs and shell scripts to deal with error states, and reported back to the person. I initially got a 'no, this isn't that sort of test. the docs work, just follow them'. After more back and forth, I got 'oh, I see that might be broken, yeah, just carry on'. I fixed what I could, made a couple commits back up, but was then told my commits needed more context, which I then added, and promptly never heard back from them again. Until... weeks later, HR reached out to say "we've gone with someone else". I recounted this story and got at least some semblance of feigned shock of 'that's not how any of this is supposed to go'. I'd kept some screenshots and emails, but they didn't care to go down that road.

tldr - Employers giving tests, please run through your own exercise processes now and then (or maybe even automate them with some smoke tests).

You could probably fix this, to some extent, by adding a sidebar to the instructions that 1) acknowledges that the procedure doesn't seem to make any sense, and 2) points out why the seemingly obvious fixes won't work. That's usually immensely helpful to me as a reader, so I don't have to waste time wondering if I misunderstood the instructions or the author misunderstood the procedure.

This is obvious for us who believe in and spend time on writing good documentation, but there are a surprising amount of devs out there who don't. "The code speaks for itself" people. Never understood them (literally) it's like some cult from the middle ages.

I write stuff for our internal teams and it's usually for sensitive systems where you can cause a lot of problems if you make a mistake. I will often start the doc by saying "This assumes you know how to use x, y, and z. If not, then you probably shouldn't be doing this." We limit access already, but some of these could be used in a DR scenario by someone who is not super-familiar with the product. I purposefully will not explain certain things because if you can't figure those out, then you shouldn't be doing these steps.

> You are a beginner for a short time.

If you have the right mindset and consciously seek to progress past it, yes.

I can recall seeing people spend years on concepts in a way where I really couldn't rule out the possibility of dedicated trolling. I remember one who would repeatedly ask about fixing problems with code examples using various advanced (at the time) graphics APIs while clearly missing several fundamentals about writing code in the language. And who also seemingly refused, the entire time, to adopt the proper spelling of "variable", despite it being corrected by multiple people in every discussion.

This is a nice idea, but looking back at how not only documentation, but also UX in general has not improved the slightest over the last decades, it's fair to say the only way we'll ever get close to anything like this is by leveraging personal LLM assistants, unfortunately.

I was thinking about the same thing. Such a classic!

But you are starting at a level that assumes you are no longer a math beginner but rather a beginner in this particular area. If you were reading a high school algebra textbook, you shouldn’t have the same issue.

My personal favourite is when I'm trying to debug something and the suggestions all say "sudo xyz".

Thanks but if I could have used admin permissions to dig deeper I would have done so already. A lot of us can't do that on company computers.

C++ might have been developed by architecture astronauts, but it's used to build a ton of valuable software - KDE, Windows, Spotify, etc etc...

Wait really?? I also wound up migrating to Fedora 75bit for basically the same reason (TopHat doesn't even support hoobastank). But then I couldn't find `file` in the specified directory. I have

`library/Lib/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam/file` and `/hahahahereiam/file.`, but neither of these boop.

Any help would be greatly appreciated.

That’s just a C enum interfaced in Swift. You can’t instantiate it, and it has no methods or any kind of functionality. It’s effective a list of numbers.

What are you expecting the documentation to say here? It will make more sense when you find where it’s used.

Edit: First link on the bottom explains exactly what it’s used for. https://developer.apple.com/documentation/avfoundation/retri...

And then there is Microsoft's annoying habit of creating APIs which return the information you actually need . . . nested three levels deep inside a bunch of their own custom data structures.

I've basically resigned myself to "it makes sense in Redmond somehow, even if it makes no sense to me."

> But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are.

It's better for maintenance (of the documentation) if the default options are only described in one place. (If the defaults change in a new version, this ensures the documentation doesn't have inconsistent, wrong descriptions. The analogous reasoning, applied to the code, is probably part of why the FooOptions class exists in the first place, after all.) But they should do you the courtesy of linking there.

This is why I rage against the crowd that promotes "self documenting code". There's no such thing, even if you should strive to make your code as readable as possible. But if there's a way to misinterpret it then you can bet many people will.

The biggest problem is that this ends up creating so much extra work. An extra 2 seconds from the dev could save hundreds or even thousands of people hours of work. I can't tell you how many hours I've spent chasing stupid shit like your example. I don't know a single programmer who hasn't.

I just don't understand why everyone's frustration with documentation (or lack of) doesn't make obvious the importance of good documentation. Every single one of us has experienced the wasted time and effort that results from the lack of documentation or from low quality docs. Every single one of us has also reaped the benefits of good documentation and seen how much faster it makes us. How does anyone end up convincing themselves that documentation is a waste of time? It feels insane

That's more about API design than about documentation though, as with a proper function name/using value objects/something else, you already know what the correct value to pass is.

It's a widespread issue though, where the API designer doesn't clearly communicate either what the thing does and/or what the thing needs.

This is why I'm sad that hungarian notation has gained into such a bad reputation. Sure, you can overdo it, but a `duration_ms` or a `response.size_bytes` or a `max_memory_mb`, or an `overhead_ns` is so much easier to use.

There are indeed languages that don't have the word "cousin" -- or "uncle" or "aunt".

The more useful answer is:

a) it needs namespaces

b) but giving people namespaces is unironically bad because it's what lead to "enterprise development" style APIs like C# where everything is named System.DataStructures.Collections.Arrays.Lists.ArrayList, as if giving something a longer name makes it more professional.

c) so instead two letters means a system framework and three letters means a user framework

Great question!

If you let someone flounder on one task indefinitely then you don't learn anything about subsequent tasks. But if you correct them too quickly you won't uncover the other approaches they would have tried to complete the task. Most research plans define cutoffs such as:

1. Participant expresses extreme frustration or gives up

2. A couple minutes have elapsed from the first failed attempt

3. Participant unsuccessfully attempts three distinct approaches

If the test reaches one of your cutoffs then the interface/docs have failed the task and the moderator can skip to the next task or question. Sometimes they'll also offer to show the participant the expected solution or explanation.

Before I saw your response I removed this sentence from my post as I realized it was not central to my main point. However, I still agree with it and am happy to explain why.

> wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts

First it depends on whether the audience for your product includes people who do not know keyboard shortcuts. If that's not your target audience then the rest of the test may not be valid anyway.

Otherwise, there is utility in forcing yourself to watch your users struggle with your product. The best product developers/owners I know have a bottomless appetite for observing people use their product, even if doing so means deferring the rest of their "full backlog of shit". Perhaps they're less efficient in the short term at churning out lines of code, but the understanding and empathy they develop makes them significantly more effective in the long term.

I cannot tell you how many times I've had to go through 30 hyperlinked pages of fluff explaining universal basic concepts before finding the five sentences I actually needed (buried in five different places).

And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.

Joel Spolsky famously wrote in the year 2000:

    > Users don’t have the manual, and if they did, they wouldn’t read it.

Maybe being able to follow a set of (seemingly silly) instructions should be part of the interview/onboarding process. And emphasised at job performance time.

When I type F5, my terminal writes "~" but nothing happens, what did I miss?

> "That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers"

tbf, that's not how I read the headline. The headline is: "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner"

The author is a beginner, which puts them in the field - so the parent comment is valid no?

> it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps

See I missed that context :D

Installation readmes are an interesting example – they shouldn’t exist. Put that effort in an install script instead.

If you want me to mechanically follow some steps, perhaps with a decision tree attached … computers are really good at that!

When someone makes a search and lands on your tutorial, you are not giving him unsolicited information.

Entirely 100% true. I can count on one hand the times I've said "wow, this documentation was written by someone who cared". Threejs is a good example here, but even then it is subject to API rot and needless reference chasing.

Examples are often the best way to do documentation, sadly.

Would asking them if they already know or would like something explained be the best thing to do (rather than assuming one way or the other)?

> you need to establish a baseline of required knowledge and skills for your audience

So many guides for setting up like... "control system simulation" or "industrial automation compliance test-bench" start with "double click the exe and press next".

Baseline for expected knowledge for the user of the guide is SOOOO important.

Hello, I am just now trying to upgrade my blog. Can you please point me to sites that do this right?

Ah, the infamous public static void main(String[] args). Hopefully the next generation won’t need to learn all those concepts up front with the introduction of instance main methods in Java 25.

https://openjdk.org/jeps/512

He’s starting with Java? I wonder if that’s the right language to start with. What is he most interested in doing? Anyway thanks for nurturing the next generation.

> Beginners have to be nurtured through lots of context that builds up slowly.

I agree and when I write for such an audience, I try to be detailed and build on a proper story that they can follow through.

I do have a complaint about attempts to smoothen the DX which a lot of projects do that results in something which helps only the absolute beginner. Logs are not easily accessible or missing. It's not easy to cut/paste or grep for errors in things etc. Basically, many of of the familiar tools and techniques which people have used to find their way through things are replaced by poor substitutes in the name of making the DX better. This, I don't think is a good trend.

I remember being in a raid guild. The guild leader was this random 18 year old kid. I remember noting that this kid was expertly herding cats, many of whom were much older professionals, with absolutely zero direct authority, across multiple timezones, and getting them to not only agreeably distribute valuable loot, but also coordinate them through intricate boss dances and more intricate event scheduling. I thought it was a real shame that this wasn't direct evidence that he should be hired into a people management role immediately.

  > They’re more like academic papers (peer-to-peer communication of new discoveries)

This made me laugh because I frequently see HN comments on arxiv papers claiming things like the authors are trying to show off with their math rather than the math just being an effective communication tool. Honestly, if anything, papers are written to too broad of an audience and we get these 10 page papers that could be communicated in 3. I'm unsure if this has been a good change. (Yes, I read the whole comment)

Just because you have access to the text doesn't mean you're the intended audience.

Probably a good thing for us to all remember here on the interwebs where everything is accessible but written for no one

I guess I disagree that it's a good thing.

As a developer, I think most documentation is terrible both for developers and non-developers alike. And if you write your documentation so that it is useful to non-developers, it's still useful for developers.

There's no downside to writing accessible documentation, except that it requires a modicum of skill and effort. That's the real reason it's so rare, I think.

I also disagree that developer documentation is like academic papers. The ways they fail are almost opposite: academic papers are overly long and overwritten, because the authors want to be very careful and complete. Developer documentation is too short and hastily written, because they often don't care if it's helpful to anybody else.

The end result may be the same: neither are useful except to a small number of experts: the people who could probably do it themselves already, and thus may not even really need the write up to begin with. But that's a failure, not a feature to be celebrated.

> One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people.

Definitely agree with this in principle. My son and I play pool (billiards) competitively. As you get better, almost nobody shares any tips because it's very competitive. I've taught him to be better than that and we have a great league team where everyone is helping the others grow.

In the mentoring (not just teaching) realm, I like to guide them into asking the questions that gets them to the answer they're looking for. When the connections in their mind light up, it's amazing.

Ironically, online recipes of the cookbook kind are actually much worse for meandering and irrelevant prose than programmer blogs are.

Maybe he and his teacher are caught in a loop ;)

And you can't write every document with an assumption that the reader knows nothing. Each document would end up the size of a phone book if you explained every single piece of technology used and provided tutorials for them.

Knowing where to jump in your stack is a tricky question, though.

Perfect HN comment parody and music reference at the same time.

> Had to explain to him public, private, internal, and also static the other night.

Access modifiers are sort of a dying breed in a lot of places aren't they? We use Go, so we're obviously still using the two it comes with, but it's public vs module only and fairly intuitive. Every other language we have in production, doesn't make use of access modifiers. Similarily while static is a thing in Python, it's hard to see what advantages it brings compared to a free function if you're using a programming language that doesn't require you to have object instances to call non-static functions. Obviously access modifiers will stick around in a lot of organisations, but there will be plenty of jobs where you never have to work with them.

The way Go handles modules, is frankly one of the few language feature of any language I've ever worked with that I wish was in every language I work with. It's so easy to use and so hard to mess up. Ok, I guess it's not hard to mess it up, but it's not intuitive.

I think Java is dying.

If you want to teach algorithmic thinking, teach Python.

If you want to teach hardware and low-level systems, teach C.

I keep saying that anyone who could run a 40-person WoW raid is almost certainly going to be a top-tier project manager.

Those raids are like herding cats. Distracted, teenage cats with connectivity issues.

Ok, my turn now. Let's build the project 'msdfgen' using cmake.

First step is cloning the 'msdfgen' repo. Done. Next step is reading the readme, which states "to build the project from source, you may use the included CMake script. In its default configuration, it requires vcpkg as the provider for third-party library dependencies. If you set the environment variable VCPKG_ROOT to the vcpkg directory, the CMake configuration will take care of fetching all required packages from vcpkg."

Google 'vcpkg' and end up at the vcpkg website. Click 'get started'. Land on a documentation page. This doesn't look like the right place. Click back and select 'browse packages' instead. This doesn't look like the right place either. Google 'install vcpkg windows'. Find a microsft site saying I need to clone the vcpkg repo. Ok. Clone vcpkg repo. Next step is running the vcpkg bootstrap script. Cd into the directory. Run '.\bootstrap-vcpkg.bat'. Next step is setting the environment variable. Open powershell. Add vcpkg to my path environment variable by copy pasting what the website tells me. Cd back into the original repo. Google how to build using cmake. It looks like I need to install cmake by first downloading the executable from the cmake website. Download cmake 4.1.1. Install.

Ok, it's time to run cmake. Navigate to the guide on the cmake website. It looks like I need to first create a build directory alongside my source directory. Open terminal and navigate to the folder just above the msdfgen-master folder. Run mkdir msdfgen-build in powershell. It looks like I now need to cd into this folder and run 'cmake ..\msdfgen-master'. Run it. It fails with three errors. "Vcpkg triplet not explicitly specified and could not be deduced. Recommend using -A to explicitly select platform (Win32 or x64)". Google what this means. Confusing. Look at the second error "CMake Error at CMakeLists.txt:70 (project): Running 'nmake' '-?' failed with: no such file or directory". Hmm, what is 'nmake'? Google it. It looks like I might need to install 'nmake' and add it to my path environment variable as well. Google it. It looks like I need to install "Visual C++ Development Tools". Google it. It looks like I need to install Visual Studio, and choose "desktop development with c++". Total space required: 10gb. Install this. Restart powershell and cd back into the build directory. Run 'cmake ..\msdfgen-master' again. Same errors.

If I had time, I'd continue down this path, but I know from experience that it will require another day or two of tooling around to get it working. I know I probably look like an idiot who doesn't understand cmake, but that's my whole point: it's a very confusing process for anyone who's unfamiliar.

Which is funny, because it's probably the easiest to use (common) build system around.

It was moved to a new path so you have to create symlinks in both locations to the new path under /usr/lib/newlib1.2/newfile.so otherwise, You can download a script that will make that for you but it will only work if you have all the dependencies for that script installed and their version numbers match the ones that the script owner had when he wrote the script.

Code can show you HOW something is done. Only documentation can explain WHY it is done that way.

If you don't need the docs then you don't need them, but sometimes we all need a "hey bro, I know you're a little lost so I'm going to break down what's happening in plain English". At a certain point you just don't have the entire code base in your head all the time and you need a reminder on what exactly the Flargle team does to all the Nargs.

Better yet would be unit-aware types. Then instead of

duration_ms = 1000

you can have

duration = 1s // or duration = Seconds(1) in deficient languages

and it's either a compile error or the type system enforces the correct conversion.

As for the bad rap of hungarian notation, it's mostly from people using it to encode something that is already clear from the types. "fDuration" helps no one over just "duration".

I quite like a terse but consistent conventions myself. I remember finally being able to quiet the tedious part of my brain that couldn't get past the NS conundrum when I finally came up with the NextStep thing as a reasonable theory.

In other words, my only complaint is that this Apple convention is not more easily discoverable. Or perhaps that the expert author of the book I was reading (this was back in the day) didn't feel the need to share it with his readers.

Exactly. You want to learn as much as possible from each study. Explaining too soon reduces amount learned, as does ending the study early because a small hint wasn't provided to get to the next step.

It's like how expert athletes often watch videos of themselves or competitors (when applicable) to understand the nuances of their play - once you understand something very deeply the small things start to matter more, until they dominate the game.

If you are a master of UI/UX and you are observing a user doesn't go through the paths you've created its an opportunity - you might be able to learn something that would make your approach more successful across a host of different users that up to this point you clearly are not winning the game against.

If you take an antagonistic approach and curse the idiot for making you watch you have not even put on a jersey yet.

Way too much documentation is like this. Then again, lots of times asking coworkers about an existing system or a new ticket that's not detailed properly ends up with them saying 30 pages of fluff to me before I can get to the nugget

Problem is a lot of times silly instructions are silly because they are wrong. Like why did you turn left and try to drive through that river? Those instructions assumed a bridge was there but it washed away 10 years ago. A new bridge exists, you can see it, obviously take that one instead.

In case you weren't attempting to make a point through irony, GP appears to be using "F5" informally as shorthand for "instruct your IDE to attempt to build and run the code". Presumably, that kind of documentation wouldn't normally literally say "F5" there unless a specific IDE had already been prescribed. The point was simply that the user shouldn't be required to do anything manual to set up the code, when starting from scratch, except perhaps to authorize the automated setup procedure.

Not going to disagree. It's the sandbox that we're playing in though (dealing with, HOORAY JAVA!) since it's a class at school.

Have to start somewhere, teach them better alternatives as they evolve. Not even going to broach the prototype-based programing stuff until he comfortably has the basics understood.

Edit: I don't GAF about downvotes, but I would at least expect a response about why. If you don't like the philosophy, give me some reasons. Don't like something else, tell me why. I'll happily debate anyone all day long

Java doesn't have an internal modifier. Concepts like public, private and static exist in Python too.

I concur with most of your thoughts, except that Java is never going away. I might wish that it would, but here we are.

And they say WoW was a waste of time.

I had to install vcpkg yesterday for the first time. Well, actually, I ran into a problem last week that could have been solved by installing vcpkg. I also happened to read a comment here on hacker news recently that mentioned vcpkg (but I didn't know what it was).

The problem was that 'cargo install cargo-show' wanted access to an OpenSSL installation (under Windows). The long error spew did mention vcpkg once or twice so I googled it and got very confused by the readme.

So I tried to install OpenSSL without vcpkg. That worked ('winget install openssl') but 'cargo install cargo-show' still didn't. Perhaps I had set up some environment variables wrong.

Yesterday, I finally figured out how to install vcpkg and it was indeed very simple, despite its readme. 'cargo install cargo-show' still didn't work -- it couldn't find openssl installed with the right "triplet" even though it was clearly installed in a way that should work for all 64-bit x86 Windows.

Setting OPENSSL_DIR and then running 'cargo install cargo-show' worked perfectly.

Apparently, there are different ways the directory structure for a vcpkg installed package can look and the vcpkg/openssl gave me one and the build script for one of the dependencies of cargo-show expected another.

Very, very confusing.

I think you can get away with just using 'winget install cmake' and then invoking cmake with the right command line to make it play nice with vcpkg (and that command line is listed in several places). I haven't tried it, though.

'vcpkg integrate install' sets up some sort of secret integration with Visual Studio -- maybe vcpkg learns where VS libraries and binaries (compilers/linkers) are hidden and maybe Visual Studio learns how to invoke vcpkg.

If you run it, it will also tell you to how to integrate more explicitly with cmake:

    $ vcpkg integrate install
    Applied user-wide integration for this vcpkg root.

    CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=/workspaces/vcpkg/scripts/buildsystems/vcpkg.cmake"

I hope this makes it slightly less confusing.

? Did you read the link? It’s used to query collections of keys grouped by the KeySpace categories, instead of a single item per key. Makes sense to me.

There’s plenty of other poorly documented Apple APIs (io_surface), but this isn’t one of them.

In code documentation doesn't support such thing. And documentation outside of code suffers from rot.

This kind of bad documentation is actually way more common in teams that require doc comments for all code, which are then promptly auto-generated by the IDE and never filled with actually useful information.

Self documenting code in this case would mean using a type that encodes the unit - which would have the additional benefit that the compiler or other tools can now check correct usage.

And conversely, there are languages with different words for "father's sister" and "mother's sister", and for male vs female cousins, etc.

But I would bet that those variable labels are never translated into other languages.

This really is one of those things that AI can improve, and already improves today.

— <https://www.joelonsoftware.com/2000/04/26/designing-for-peop...>

    > I think Java is dying.

There are millions of enterprise programmers around the world that use it. If it is dying, then what is replacing it in the enterprise? From my perspective, I don't see any serious competition.

At the moment, I see this pattern for mega enterprise:

* C++ for scientific, mathematical, financial core libraries

* Java for heavyweight backend services that run on Linux

* DotNET for thick clients that run on Windows desktops/laptops

* NodeJS for lightweight backend services that run on Linux

* HTML/CSS/JavaScript (plus frameworkds) for lightweight web apps

* Python for data analysis and AI/ML work

Access modifiers are useful, albeit not for beginners. They're most useful in statically typed languages with good tooling where they keep auto-generated API docs and autocompletions clean.

Static methods are useful for namespacing, e.g.

    var instance = SomeThing.fromString("...")

In some languages you can of course make a global free function called someThingFromString which does the same thing, but then (a) it won't have access to private methods so the public API surface gets more polluted with stuff the user maybe shouldn't call themselves, and (b) it won't show up in the right place in generated API docs and (c) it won't show up in the expected place in type autocompletion.

Kotlin has both static methods (or rather companion objects which are an equivalent), and also top level free functions, and when writing it I find myself creating static methods a lot more often for the above reasons.

I beg to differ. It's only easy for projects you're constantly using daily. People tend to build all sorts of abominations with it.

This answer is correct but it only works under a new moon if you implement while smoking a joint rolled in pink paper, which should be doable.

> It’s used to query collections of keys grouped by the KeySpace categories

Sounds like something that should be mentioned in the opening sentence of https://developer.apple.com/documentation/avfoundation/avmet...

Some varieties of in-code documentation do support links, e.g. XmlDoc which is the de facto standard for documenting C# code (and therefore the most relevant to my comments about MSDN because I was referring specifially to the .NET API documentation) has multiple ways of embedding links in your in-code documentation comments: https://learn.microsoft.com/en-us/dotnet/csharp/language-ref...

MSDN even uses those, a lot. But not enough. I wish that every time they had a "Foo(string parameter) - uses the default FooOptions" it was a link to the documentation section where the default FooOptions are listed. But usually you're left to find the default FooOptions yourself, which means 5-10 minutes of digging through docs (1-2 minutes if you're lucky) that I could have spent writing or reviewing code instead. That adds up.

We are talking about MSDN not some source files. Even if those pages are generated from in-code documentation that generation step can use whatever transclusion mechanisms Microsoft wants to add.

You would be if it's a tutorial on audio codecs and your tutorial starts with connecting the power cable to the computer, clicking 'log in', and don't forget to breathe!

The install script may not have all the context it needs to be installed. In the long run it is better to teach the user how your software works in plain english.

Even in projects with an install script, for example pmbootstrap, the install script also needs a tutorial.

In my experience, projects with minimal documentation and an install script will have the the install script fail halfway through because it assumed something about my system that isn't true, or it will do something incredibly insecure like requesting su and then curl | bash

I've been leaning on test suites more and more for this. It's almost like a test suite should contain comprehensive tutorials. You know the API is good (hopefully) because if it isn't, the CI/CD pipeline wouldn't have let the release through.

That can also easily be misconstrued.

"What is an exe?"

I agree with you. I'm no fan of C++.

With that being said, it is (and has been) used to produce valuable software.

You never need to use everything a language provides. You find the parts useful to you or your team and use all of them.

I was a C++ developer for a decade and knew a fair amount of the C++13 spec but never needed to use even half of it in production. I've been a Java developer for years and don't know 10% of the standard library there. That doesn't make either language poorly designed by itself.

Huh TIL, my apologies.

I actually think the inscrutable Main method in java has some value. As a kid, I loved to know how things worked and always did things like read instruction manuals and read ahead in school textbooks. I wanted to know everything about anything, and I wanted to know how it worked from the bottom up.

The java main method taught me "This is abstraction, an important concept in programming. You won't always know how all the magic works all the time"

It taught that you have to deal with black boxes.

Also, I never saw it cause problems in CS101 classes, because the kids curious enough to want to know something their professor didn't explicitly talk about were usually the ones who would do fine at learning all the parts of it.

The kids who struggle with programming never seemed to have problems following "Just write your code here, you will learn more about it later"

The headline has been edited, in its current shape I tend to agree to you.

The struct is only named on the link you provided, not documented. So thanks for showing the absolute irony of it not being greatly documented, allowing people to misinterpret what it means.

An extreme example would be gwern.net -- specifically you might want to read https://gwern.net/about and https://gwern.net/design

Reminds me of the (now decades old) humorous observation that the entired R5RS (Scheme) book is shorter than the table of contents of the C++ spec.

I fully disagree with Java as a starting point and it was an interesting conversation with the teacher.

Apparently, "College Prep" courses more or less determine that Java is the language that they should use.

His teacher thought it was stupid as well, but sometimes your hands are tied. That's what the schools are using as a starting metric though.

He was apparently the only person in the class that said he wanted to do software engineering. Don't worry, he'll be a polyglot before he reaches college.

Because it’s a boring enum in C, auto translated to a swift struct.

And if you’re reading the documentation because you do development, then you would already know that the header files are installed on your computer and you can trivially verify that there is nothing to document because it’s just a query key.

Enums get documented everywhere else. If nothing else, you need the range of options!

Going off to read the header file means it isn't documented.

I probably shouldn't have worded it quite the way I did. Considering I praise Go's access modifiers. What I meant was the "old" way of having lots of them and explicitly having to write them out. I haven't tried Kotlin but it sounds nice.

What I like about Go is the simplicity. Everything inside a folder is a package/module and any method beginning with a capital letter is public while every method starting with a lowercase name is package/module only. Coming from a decade of C# it was such a nice thing.

I do work with a lot of Python where you don't have private methods. I mean, you can set up your corporate environment to "hide" _methods or whatever, but they are never turly private, and static methods are... well... they are basically just namedspaced top level functions.

Thank you. That is indeed quite extreme - I could use an article progress bar, footnote pop-ups (maybe, link back into article might be enough). Definitely not doing my own window manager. I'll try and read the rest of the design page with fresh eyes, maybe I'll learn something else.

Lmfaooooo..... to everyone else reading, cpp programs are indeed successful, but they are successful in spite of cpp, not because of it, is my assertion. It is increasingly rare to find major applications using the newest cpp features, because of how obtuse they are for 99.9999% of people, including extremely good programmers, of which a Youtube search could produce 12

Some notes:

.NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good.

NodeJS does nothing better than anyone. The only things I can think of that make node worth using is electron and react native, maybe Next but I'd much rather do SSR in a real programming language personally. I would never use node as a pure backend, there's just no reason to and JS is an F tier language. TS brings it up to like C but it's still just not good enough to compete.

I can't see any reason to choose node for typical backend programming and such unless your devs only know JS. Any other language is probably better suited.

I learned Java in uni and think it's a fine language to start with. It's also been modernized a lot in the past decade, and if you really want a more modern language it's easy to transition to Kotlin.

I'd take Java over Python or JS any day. It wins on performance, it wins on type system, js is just a plain trash language not at all suited for general purpose programming (TS solves some problems but not all and it has its own problems) and python is fineish but it's slow and just kind of icky, I'd never do serious software development in python. It's fine for small scripts and notebooks and such, we learned python as part of our math classes while the programming classes focused primarily on Java. We also had a class on web development using JS, ML using Python and windows programming using C++ and C#.

I struggle to see any significantly better candidates for a first language than Java. Sure you could go with C but nobody really uses it any more outside of niches. C++ is out, too much stuff. I really like C#, it's my daily driver and I wouldn't mind it as a first language but I think Java is more approachable for beginners. Less confusing syntax to learn. I don't know Go but maybe that could be an alternative? Other than that I'm a bit out of options.

Java is a fairly simple language that's easy to learn and allows teaching a lot of important concepts that will be useful in other languages moving forward. That's a big thing I think, it's not meant to be the only language. The word polyglot is used some times, to me it just means programmer. I don't know any competent developers who only know one language. You end up learning multiple and I think Java is a good entry point.

Java's a pretty good beginning programming language. Outside of the mystical incantation of `public static void main(String[] args) {` and what the difference between `new ArrayList` and `ArrayList.new()` is (I still don't know but I haven't really touched it since college), it's a good statically typed imperative language that you can throw objects and functional stuff into when it's time, isn't going to give you weird errors about indentation, has just enough pointers for you to learn how to avoid a `NullPointerException`, does things pretty "conventionally" (ie, there's not a lot in Java that doesn't also show up in other languages), and is easy to compile and run (when you're not using 3rd party libraries, which students in something like a Data Structures and Algorithms class aren't going to be using). Ideally you have another class teaching you another language too so you get the double bonus of learning what a language is and what a language isn't, and Python's good for that, but by itself Java's fine

My first programming class was Java. That was 8 years ago. Maybe the curriculum designers thought Java would be relevant for the workplace? The education system always lags several years behind industry trends.

I agree with lots of things in your reply. In an enterprise setting where you mostly don't care about size of deployed application, then Electron is a godsend, where you can deploy a 500MB "Hello, World!" desktop app written in HTML/CSS/JS/TS in an afternoon. I know all about the bloat, but 99% of enterprise users don't care. A good web programmer can pump out very slick desktop apps incredibly quickly using Electron.

    > I can't see any reason to choose node for typical backend programming and such unless your devs only know JS.

This is the primary explanation when I see NodeJS backends in enterprise. Mostly, those projects only have medium to low skill "web devs" (sorry, I cringe when I write that term).

> Outside of the mystical incantation of `public static void main(String[] args) {`

I don't think it's mystical. If you don't have an instance of the class yet, you need a starting point and static fills that void (lol. I'll show myself out)

".NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good."

Last time I tried NET was 15 years ago, so I have no first hand knowledge anymore, but I do read regular complaints, that cross compiling to Linux(or developing there) comes still with major hurdles at times?

C# is amazing. Decisions at the education level were made well before it went cross-platform though (FWIW, I've been using it since before v1.1).

Would be interesting in what confusing syntax you're referring to. I think one of the beauties of it is that it's additive. You can program plenty of simple stuff in it with conventional style code, but there's a lot of syntactic sugar available that makes things so easy when you need to start scaling things.

My first programming was also Java. That was...27 years ago! That's some lag.

Nah, DotNET is amazing these days. At the risk of starting a holy war, it is neck-and-neck with Java, and I say that as a Java fanboi. I think it is good to have healthy competition between languages (and ecosystems), like C++ and Rust (and a little bit Zig) or GCC and Clang or Java and DotNet or Python and Ruby or NodeJS and Deno. Plenty of people are compiling and deploying to Linux after DotNetCore went open source. Plus, you can use JetBrains Rider, which is a cross-platform IDE for C#, from the makers of IntelliJ.

> 27 years ago!

Sometimes, I feel like I'm the only old guy on here. BASIC, VB6, .NET, and some Java along the way.

Too many new ones to list, although that might be a whole other problem in itself.

I agree, C# is my language of choice and I've been using it professionally for over 5 years. I use it for personal projects as well.

I'm referring to all the stuff C# has that Java doesn't. Async, ref/in/out keywords, extension methods, linq, lots of stuff. Maybe it's not a big deal, like I said I wouldn't really mind it. I just think Java is a bit simpler in this regard which is an advantage for beginners.

Some differences where I prefer java are checked exceptions and imports. C# usings are ambiguous, it can be difficult to figure out where things are coming from for code samples outside an IDE. And checked exceptions are just good IMO. I've never seen why people dislike them, having used Java and C# I think Java does it better. It's easy to miss exceptions in C#, I wish library developers could use checked exceptions to tell me which exceptions I should worry about.

Anyway both languages are great first languages and great general purpose languages. Highly recommend both.

.NET is amazing and keeps getting better. JetBrains is killing it with their IDEs and add-ons.

Currently running nearly a dozen different services written in .NET running on Alpine in K8S.

Started transitioning most of my code to .NET Core/Standard when they first came out. Sadly, I still have to deal with some ASP.NET MVC code that was written before and requires .NET Framework

Thanks for taking the time to respond. Ultimately though, most of those aren't required from the beginning, but the syntactic sugar, abstractions, and performance gains from them are amazing.

You probably already know, but I'll opine a little bit about extension methods. I use them a lot.

Entities > Repositories > Functionality. All split out.

- Entities (pretty much just gets and sets, nothing more than necessary).

- Repositories via extensions to determine where the data comes and goes from (some data comes from SQL, some from Redis, some from Postgres, doesn't matter since it's split out) and any particular queries you need for optimizing things.

- Functionality via more extensions without adding additional code to the entities.

Separation of purpose/use.

I may or may not have completely replaced our data layer in the middle of the height of our season with no interruption. Little bit passionate about this one.

Would you happen to have something like a github repo with examples of those repositories? I'd be interested in seeing that.

Personally I'm not a big fan of copious extensions. I use them some times but I'd describe my usage as sparingly.

I wish. It's on Github, but my hands are tied and I can't share them since it's someone else's property now (hooray for exits, I think).

It's mostly a thought process...

I have or need something (entity), lets get data about it (repository/extensions), we need to do something with this now (only extensions).

Lots of "static" and "this" involved, but the separation and eventual simplicity makes it worth the effort.

Edit: I tried going through some of them to anonymize some for examples, but it felt like treading in dangerous territory.