A guide for how to talk to a developer | Hacker News Reader

A guide for how to talk to a developer

hatchapps.com

31 pointspencildiver42 comments

This is painful.

If, as an employee you're so engrossed in technical jargon that you can't explain it at an understandable and reasonable level to a competent adult, there's a problem.

Likewise, as a manager, you memorized some flashcards and now "understand" enough to throw around some buzzwords and jargon, that's going to have it's own set of problems.

Talk like a human, ask questions, and don't be an idiot.

And if one of the two things you "know" about C is that it's "uncommon".. Best not to remove all doubt.

Flagged article because it is beyond stupid

1. Is this for real?

2. Here are exactly two things that you need to memorize in order to make this sort of talk productive:

a) I don't know what X is, sorry. Can you tell me what that is/Can you explain to me what it does?

b) I'm not sure I follow. I thought X is [...]/does [...], what am I missing?

3. Did anyone who actually knows what these things mean review these definitions? E.g:

Vanilla:

"Plain or basic, often used in reference to coding languages or other computing-related systems that remain unmodified from their original form."

There's nothing plain or basic about the vanilla Linux kernel. What makes it vanilla is the absence of distribution- and/or vendor-specific patches that are not in mainline.

API:

"A set of rules that developers follow to create software that can interact with an external system or application."

This sort of matches what an API is in web land, if you squint a little. If someone were to ask me what that definition describes, "API" is about the last thing I'd say.

Django:

"A style sheet language that extends from CSS."

Last time I wrote web-related code, my girlfriend dragged me to see The Aviator twice because it was all the rage, and I haven't really kept up, but I could swear Django is not a language and that it doesn't extend from CSS, whatever that means.

> API

Yeah, I'd say an API is the interface that you expose so that other developers or systems can interact with your project. That can be over HTTP if it's a web service, but it can also be the interface that you expose from a library that's intended to be used by other developers. Python's Requests is based around the idea of exposing a better API than the stdlib's to manage HTTP requests. Win32 is an API, and so is Cocoa.

> Django

Uh... generally speaking, Django is a Python web framework. It has its own templating language, but I don't recall any facility specific to CSS. That one is just weird.

>This sort of matches what an API is in web land, if you squint a little. If someone were to ask me what that definition describes, "API" is about the last thing I'd say.

I struggle with defining simple things like this, and I think what author offers is a good generic way to define API. This definition includes any actual way I can imagine one can get (programmatic) access to generic service that does not belong to them. I would really like to know how you would define it though.

A user interface is how a person talks to software. An API is how software talks to software.

An API is like a restaurant menu, but for software. A menu tells a person what they can request from a restaurant. An API tells a programmer what their software can request from other software.

Excellent definition.

The second part is true when there is a documentation.

Rather than memorize a bunch of flash cards it seems much easier to just talk to them like humans and if they say something you don't understand don't be embarrassed to ask them what it means.

I know non-technical people who, when they think they are hearing anything remotely technical, seem to shut down and go into "I don't know technical stuff!" mode...

Not that flashcards are going to cure _that_.

I think you're right. I also know technical people who obscure gaps in their own knowledge with jargon. So clarifying questions that might expose the gap are responded to with increasingly technical rambling. Bad habits all around, feeding off each other.

Increasingly technical rambling is good. What I hate is when techies start to imply that whoever they talk with is an idiot after they reach limit of their knowledge. That tactic is used surprisingly often.

It makes people scared to ask and passive.

No he means increasingly technical rambling that is also meant to obscure the fact that they don't know the answer. Definitely not good.

True, but one-sentence explanations can be helpful for managers and PMs that aren't familiar with the specific tech stack to get up to speed quickly.

I don't think this is a bad idea per se, but I do think that it's got a long way to go before it's really useful (or even correct).

It looks like it's just several flash cards to help managers talk like Pointy Haired Boss from Dilbert.

It is. And it should be titled as such. The current title calls it a "guide", which is misleading.

Some of these are just wrong. "Django" is not "A style sheet language that extends from CSS."

And an API is not quite "A set of rules that developers follow to create software that can interact with an external system or application" [emphasis added]... (Gives the impression of a design pattern or something, IMO)

This is awful.

Now you ruined the fun of some boss trying to say he understands Django :(

The UI is pretty, but that's about it.

How about you just talk to a developer like a regular person? Don't understand what an API is? Just ask them. Great folks love explaining things to others, and if you're not a developer yourself, it's not too stupid of a question to ask (or simply Google it).

The "computer science" terms are funny. That's not computer science, that's web project development.

"Agile - A adapted method of project management in which tasks are divided into short phases, and plans are regularly revisited and modified in response to new information."

What does "adapted" mean in this context, anyway?

I think they mean "adaptive" in that it adapts to changing circumstances.

That's worse. "Adaptive" in web-level tech speak is related to features for disabled people.

Just leaving the word out would improve that sentence.

If you’re a manager of developers and you need these cards to tell you what some of these things are (database, stack...) you probably shouldn’t be managing developers.

Surely as developers we should be able to reduce or explain our use of jargon for the person we're speaking to, rather than the rest of the world having to learn our industry-specific language?

I try not to use any jargon at all when communicating to non-dev stakeholders, and they still complain about jargon.

Words like "server" or "database" are not jargon. There are literally no other words to use for those things. And if you don't want to hear any technical-sounding words at all, then don't ask technical questions. Or better yet, don't work at a tech company.

This is as condescending as it is wrong.

IMO, being wrong makes for the most amusing condescension. This website is excellent in that regard, but otherwise remarkably wrong!

Shoot, well if this is the way the world works, I better get some flash cards to talk as a doctor/mechanic/craftsmen/anything-else before I even think of talking to them. The horror of asking what something means is too much!

Django - “a style sheet language that extends from CSS” what blasphemy!

"Django is a free and open-source web framework, written in Python, which follows the model-view-template architectural pattern. It is maintained by the Django Software Foundation, an independent organization established as a 501 non-profit. Django's primary goal is to ease the creation of complex, database-driven websites."

The flashcard is uhh, close?

Just No. It doesnt't even feel human. It's like throwing bunch of things at the developers and will give out output. It's upper management version of random button smashing.

I sent them a message offering to review their definitions. There's a lot that are incorrect, but complaining about it doesn't solve anything :)

This is quite funny. Not the website itself, but the comments on here. And it proves the point so well! The website in question is a seemingly obviously quick project that someone whipped up quickly on the hatchapps website. But almost all of the responses here seem to think it's a serious project, taking it at face value.

And therein lies (one of) the problem(s) in talking with developers. We (developers) assume what you (the customer) said is what you meant, but it rarely is.

First there was mansplaining, now there's devsplaining.

‘Mansplaining’ “You Keep Using That Word, I Do Not Think It Means What You Think It Means”

More clearly. I don’t think you know what mansplaining means.

> More clearly. I don’t think you know what mansplaining means.

That is unnecessarily hostile comment.

I don't care what you think. I know what it means and you have exactly zero reason to publicly doubt that.

If you look past the poorly-thought-out title, this page is actually a good information resource for non-technical people.

If it was cleaned up a bit sure. The title totally ruins it... how elitist can tech people get? Go study this glossary of terms THEN you can talk to me.

Except for the part where a bunch of the definitions are wrong, misleading, or woefully incomplete.

>Except for the part where a bunch of the definitions are wrong, misleading, or woefully incomplete.

Examples?

Have you read this thread? I personally stumbled hard on the definition for Firebase ("essentially equivalent to AWS" -- I might be paraphrasing slightly since it's been a day).

Reply on news.ycombinator.com