Something like the mock one here I think is really more often largely intended as a sort of logbook entry, a note to self, 'how I did x' (in case it breaks, I need to do it again, update it), it isn't really 'for me', the other.
How I, a non-developer, read the tutorial you, a developer, wrote for me
271–280 of 455 posts
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#272Earlier quoted context omitted.
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…
".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?
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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#273Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot user…
I always write my own notes when setting up to "fill in the blanks" of the guide, then I create PR with them.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#274Earlier quoted context omitted.
> 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…
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…
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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#275Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#276Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot user…
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 u…
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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#277You could replace specialized terms with nonsense words in anything. This is completely non-actionable critique.
In the end, there is no Royal Road to learning. You have to create put in the effort to create new concepts in your head to understand something.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#278Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot user…
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 u…
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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#279This is how I feel trying to follow tutorials for using LLM or GenAI (LoRA, agentic, MCP what?)
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#280One of my first policies: Every time we have a new hire, the first thing we do is have them go through our onboarding documentation and ask them to make corrections, improvements, and add clarifying notes.
It's their first contribution to our code base.