Comment by zestyping | Hacker News Reader

Comment by zestyping | Hacker News Reader

Parent Full thread

The writing style is just insufferable. Even the API documentation is littered with hyperbole and self-congratulation. We get it, you're proud of your work and extremely proud of yourself.

> "as simple and powerful as glom"

> "big things come in small packages"

> "small API with big functionality"

> "power is only surpassed by its intuitiveness"

> "simplicity is only surpassed by its utility"

> "shortest-named feature may be its most powerful"

For heaven's sake, give it a rest!

It's a big red flag about your priorities that when I go looking for a precise specification, I can't find answers to simple questions and instead end up wading through incessant marketing phrases. I tried, and I finally gave up halfway through the API doc. It might even be the case that glom is a good idea—but you're making it really hard to trust you as a source of objective information about it.

Show, don't tell. My advice to you: you'll generate more interest if you delete every congratulatory word on those pages and focus entirely on helping your readers understand what glom does instead of trying to sell it to them.

Hey Ka-Ping! Maybe I did get carried away :)

How I wish one could publish a dry document and expect people to read all the way to the bottom. I've published enough libraries to know that's not the case. glom's free software so it's all there, as "shown" as can be.

But referring you to the code wouldn't be very considerate either. Instead, here's this literate code version that I prepared in advance. Hopefully this will be of more help to you: http://glom.readthedocs.io/en/latest/faq.html#how-does-glom-...

Thank you for glom, and don't let those comments get you down.

Personally speaking – my heuristic is that maintainers who put effort into marketing copy (even if it's awkwardly exaggerated) are the kind of people who really want their users to enjoy the project, and that often predicts a low-friction experience. Keep doing what you're doing!

Dude, this looks really nice! I use nested stuff like that all the time - nested layers of flat data ;) - and glom (+T) do seem super appropriate and nice!

My only concern is that the documentation renders poorly on mobile. So I couldn't read the right half of the page.

I was frustrated. I apologize. I do still believe the frequency and intensity of hyperbolic language is a real obstacle to understanding and appreciating your project, and I hope you take that feedback to heart. But to call you "extremely proud of yourself" was unnecessarily personal, and I'm sorry I said that.

Looks like a nice package. I will try it in my next project. The upcoming features sounded interesting. Keep up the good work!

In http://glom.readthedocs.io/en/latest/tutorial.html#access-gr...,

> After years of research and countless iterations, the glom team landed on this simple construct:

'years of research', 'countless iterations', 'glom team', really?

You're yellin at a tutorial man. You gotta let some flavor text slide. :)

That said, I'm no liar. Kurt and I (as a team), really did write stuff leading up to glom in 2013 (years ago), and have written stuff like it enough times that I've lost count (countless :P). If this isn't research, I don't know what is. Heck, I'm even getting a fun little peer review!

You've created something useful and it will save a lot of programmers a ton of time.

I didn't find your writing insufferable. I've written tongue in cheek (or over the top) posts about my projects in the past. If they can't see the humor and the usefulness of the project, their loss.

Thank you for creating Glom and thank you for posting it on HN. Count me in as one of your users.

don't sweat it dude. I've noticed a lot of people on hn are crabby assholes for absolutely no good reason. like on the post linking to Google's codelabs (where there are hundreds of tuts about all sorts of things in the Google ecosystem) there were only two comments and they were complaints. and recall that every time an electron app is posted almost every comment is whining about the performance. and every time a rust article is posted there's whining about how it's more complicated than js. and every time there's a js article posted there's whining about how it's not type safe like rust. and every time someone posts a personal page someone has to point out how it's "garbage on mobile" as if they're doing people a favor pointing out flaws (as if they don't understand that mobile is the most heterogeneous platform out there). I swear people don't know how to be grateful for free shit or just keep their mouths shut when something doesn't tickle their own particular fancy. I wager it's a defense mechanism because they themselves aren't making anything and so they need assert their superiority in some way (because people that are busy doing stuff don't have time to complain about things irrelevant to their own work). kudos to you and Kurt for releasing a library to the community that's different and interesting and fuck the haters.

This needs to become a copy pasta + a version where we s/hn/reddit/g and every friggin salty post needs it shoved to them.

Also, often it's better if power surpasses intuitiveness a bit. :)

you know what's actually insufferable? taking pot shots at someone giving you something for free. either say thank you or move on. it's like yelling at your mom for making you breakfast in the morning: downright unseemly.

if the condescending tone of the top comment is ignored it becomes valuable feedback. good libraries/api's (free or otherwise) do not need to use marketing buzzwords to sell themselves when a clear demonstration of the functionality is usually more than enough.

see the python requests library documentation for a good example

http://docs.python-requests.org/en/master/

Did you seriously just recommend Requests, a project which uses "Non-GMO", "organic", and "grass-fed" to describe itself on the very page you linked, as a good example of not using buzzwords?

Come on. kreitz holds the title of Python marketspeak tycoon for a reason. :P

You forgot the line that's the biggest offender of all, "... for Humans".

>if the condescending tone of the top comment is ignored it becomes valuable feedback. good libraries/api's (free or otherwise) do not need to use marketing buzzwords to sell themselves when a clear demonstration of the functionality is usually more than enough.

this fallacy is called affirming the consequent. yes good libraries might not need marketing but that does not say anything about whether good libraries can have marketing.

its anyone's best guess whether apis/libraries with documentation that have buzzword-y marketing get more usage than those that entirely market themselves based on functionality.

Think of buzzwords as familiar faces for the readers. Sure, you can overdo it and make a buzzword soup, but a few buzzword can give the reader a quick idea of the product.

I think the more practical piece of advice is for people like zestyping to constructively offer their (valid) perspective on writing style without personalizing the criticism. I recognize however that offering such advice may be a fruitless endeavor depending on the person (like expecting a leopard to change its spots). Source: zestyping needlessly insulted me in front of colleagues over 10 years ago and it still stings a bit :-D

I think that practical advice is good.

Publicly deriding me as having an irreparable character flaw, based on something I said over ten years ago, which I can't possibly defend or apologize for because I have no idea who you are or what you're referring to—doesn't that seem a little low, though?

It sounds like this is still bothering you after all this time. Please consider reaching out to me (my e-mail address is my HN username at gmail); I'd be glad if we could sort this out in a private conversation. I can't promise that I'll take back what I said without knowing what it was, but I will do my best to understand what you experienced and why it was upsetting to you.

Reply on news.ycombinator.com