Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How I, a non-developer, read the tutorial you, a developer, wrote for me

anniemueller.com

Post reply on HN
Print view View original

201–210 of 455 posts

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#201

Post by al_borland »

throwaway2037 wrote: post #179
al_borland wrote: post #172

Earlier quoted context omitted.

I've written a lot of docs, and one big issue I saw play out over several years was watching the overall skill of the team members drop. They were told by their manager to use the docs, which they did, and then seemed unable to think outside the docs when needed. For tier 1 support roles, I think the docs were helpful to get them going, but it seemed like the docs acted as a crutch for most of the team, to never be a…

I think that you are interpreting this outcome as technology-wise negative. Instead, I will offer a commercial positive: If the docs that wrote are so great, then you can hire lower skill, cheaper support staff. Training is also cheaper (because of docs). If I was senior IT mgmt or biz mgmt: That is a win. > never be able to grow in their role and move up to tier 2. I'm not sure how to solve for this problem. I have…

In the past (20 years ago), those tier 1 roles were a great feeder for the organization. Because that role touched so much, it meant everyone had a lot of perspective on the organization as a whole, and thought about support and maintenance while building new things.

It’s easy to say who cares and hire from the outside, but that organizational context and care for support is lost. People build whatever and throw it over the fence, which makes everything worse, imo. Those people also tend not to stick around, so they have no skin in the game and it’s hard to develop culture as people rotate in and out frequently.

There are always some people who will never learn, and these people are cheaper, but there are other hidden costs as you seek to optimize for low-skill workers.

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#202

Post by mcdeltat »

I wrote about this a while back [1] because most documentation is just plain bad. At best it's a reiteration of what is obvious and at worst it doesn't exist. Far too often it says too little of the bigger picture and too much of oddly specific edge case details. If I can't come to your project from 0 knowledge about your project and get it running without tearing my hair out, the docs failed.

[1] https://mc-deltat.github.io/articles/what-the-f-is-this-code...

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#203

Post by derf_ »

Schiendelman wrote: post #188
ocimbote wrote: post #88

Earlier quoted context omitted.

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 (tru…

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.

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.

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#204

Post by aDyslecticCrow »

efitz wrote: post #190
aDyslecticCrow wrote: post #181

Earlier quoted context omitted.

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

Wow, way to double down on “I really hate everyone who doesn’t have exactly my skill set and experience.”

I'm ... confused what you mean. If the junior is gonna untangle the docs anyway, why not make them directly update the parts that confused them once they're through it.

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#206

Post by sfn42 »

marklubi wrote: post #89
bckr wrote: post #82

Earlier quoted context omitted.

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.

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…

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.

Re: How I, a non-developer, read the tutorial you, a developer, wrote for me

#208

Post by Dilettante_ »

begueradj wrote: post #47
ShroudedNight wrote: post #34

Earlier quoted context omitted.

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 wo…

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

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!
Post reply on HN