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

321–330 of 455 posts

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

#321

Post by marklubi »

ranger207 wrote: post #287
marklubi wrote: post #89

Earlier quoted context omitted.

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…

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

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

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

#322

Post by rdtsc »

SoKamil wrote: post #234
card_zero wrote: post #119

Earlier quoted context omitted.

No it isn't: How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner How I, a beginner developer, read the tutorial you, a developer, wrote for me

We are kind of both correct. GP mentioned: > The title of the blog post currently is: > > How I, a non-developer, read the tutorial you, a developer, wrote for me > The HN title is: > > How I, a beginner developer, read the tutorial you, a developer, wrote for me So GP cut off , a beginner ending which in turn falsified my claim of it being longer, and I didn't verify blog title.

My apologies, SoKamil, for cutting off the ending in the comparison. I wanted to highlight the difference and figured the first part is where the difference was. As in, they are still a non-developer and shouldn't have to learn all the details so it doesn't matter if they are just a regular non-developer a beginner non-developer.

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

#323

Post by elzbardico »

rdtsc wrote: post #70

The title of the blog post currently is: > How I, a non-developer, read the tutorial you, a developer, wrote for me The HN title is: > How I, a beginner developer, read the tutorial you, a developer, wrote for me Those are different things. A "non-developer" reads as someone who isn't supposed to understand any of this. I am imagining a human resource person, a customer completely unfamiliar with internals, someone f…

In the end, lots of people who try to accomplish their goals writing some code don't see themselves as beginner developers but non-developers.

They just want to accomplish some well-defined and scoped task that happens to require some coding, but they have no interest, at least for now, on becoming developers.

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

#324

Post by skydhash »

mschuster91 wrote: post #256
skydhash wrote: post #180

Earlier quoted context omitted.

Those are references, not tutorial. They are there to refresh your memory. Usually you look for code examples or a guide for learning how those work (even AOSP apps if needed)

> Usually you look for code examples or a guide for learning how those work ... which in practice means, particularly for stuff that recently changed, that you go to StackOverflow only to find out that the majority of posts are horribly outdated and don't even compile any more. The other side are code examples that technically work and show, say, the syntax on how to use a programming language's or framework's shiny…

I was reading The Art of Unix Programming (E. Raymond) and one of the advices was that every library should come with a program. So even it’s a todo list kind, I think it’s quite nice to have.

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

#325

Post by CaptainOfCoit »

Aaargh20318 wrote: post #241
imgabe wrote: post #225

Earlier quoted context omitted.

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.

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

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.

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

#326

Post by tomatohs »

nomilk wrote: post #48

Can'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 started a company to do exactly this a few years ago, and got to work with amazing companies testing their developer experience.

The problem is not the docs, it's Conway's law. One team designs the API, the other team designs the portal, and another team designs the SDK. The user has a holistic experience that cuts through each team.

That, and the docs are usually written first by the most technical person around, who has a hard time sharing the world view of a noob.

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

#327

Post by maxloh »

skydhash wrote: post #180
maxloh wrote: post #138

Earlier quoted context omitted.

I think the JavaScript ecosystem did a great job at this. Take a look at the documentation of React/Vue/Svelte; it is fascinating how they make it so accessible, both for newcomers and experienced developers in the field. In contrast, the Java ecosystem has been really bad at documentation in my experience. Most of it is just explanations of function signatures, without any words on how those functions work as a whol…

Those are references, not tutorial. They are there to refresh your memory. Usually you look for code examples or a guide for learning how those work (even AOSP apps if needed)

As far as I recall, many libraries in the Java ecosystem, as well as the Android API, don't have the official tutorials or guides you're referring to. The JavaDoc and the Android API reference are often the only officially available resources.

So no, Those aren't just there to refresh developer's memory. In many cases, they are the only resource for learning the system from scratch.

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

#328

Post by dendrite9 »

golph wrote: post #105
nomilk wrote: post #48

Can'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'm a Jr. sysadmin at a medium sized software company. Whenever I document workflows for our users, I have two colleagues of mine who have no connection to IT work through them and add the small gotchas they asked me to the docs. It saved me a whole bunch of headaches for when other users get enrolled in these workflows.

I've been doing some cal/QC functions recently after years not touching it. Since I last did it I've forgotten some of the knowledge that is just assumed. The answers to my questions are documented, but not in a places that is accessible from the production side and has lived as community knowledge in production. I've been making a list and updating the documents to fill in some gaps.

Unfortunately some of the production people aren't comfortable enough pushing for changes in the documentation so some of my job now is to ask what they've noted and get it added.

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

#329

Post by marklubi »

sfn42 wrote: post #206
marklubi wrote: post #89

Earlier quoted context omitted.

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

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.

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

#330

Post by ctrlp »

I don't see why there's an expectation that a "non-developer" should be able to understand documentation or tutorials written for beginners. It's a specialized field with technical jargon. There's a reasonable expectation that the person reading your tutorial is at least marginally competent. Beginner doesn't necessarily mean "non-developer." It could as well mean "new to this stack/technique/idea." I know this was written in good fun, but the implications that you shouldn't need some baseline competence to work through a tutorial is just wrong-headed. It benefits the reader to run into roadblocks and work through them. That's how you learn.
Post reply on HN