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

Just Simply – Stop saying how simple things are in our docs

justsimply.dev

Post reply on HN
Print view View original

271–280 of 299 posts

Re: Just Simply – Stop saying how simple things are in our docs

#271

Post by ulizzle »

spondylosaurus wrote: post #247
ulizzle wrote: post #197

Earlier quoted context omitted.

It's an improvement because it cut out all the adverbs. The tone of the essay is an unmistakable virtue signal. It tries to correlate the virtue signal with quality improvement, which is either cringe or disingenuous.

Completely disagree that this is a form of virtue signaling; everything the article outlines is reflected in the major documentation style guides (e.g., MMoS or the Google developer documentation style guide). - Don't make unsubstantiated claims about your product. - Don't discuss upcoming features or refer to existing features as "new" outside of announcements/release notes. - Don't make promises about uptime or oth…

If you completely disagree, keep in mind “completely” is also an adverb.

Some frameworks sell simplicity (setup, maintenance) as a feature, so that adverb would be fitting.

But this is just infantilizing and a lot of people (maybe a universal trait) are annoyed by that.

Re: Just Simply – Stop saying how simple things are in our docs

#272

Post by spondylosaurus »

ulizzle wrote: post #271
spondylosaurus wrote: post #247

Earlier quoted context omitted.

Completely disagree that this is a form of virtue signaling; everything the article outlines is reflected in the major documentation style guides (e.g., MMoS or the Google developer documentation style guide). - Don't make unsubstantiated claims about your product. - Don't discuss upcoming features or refer to existing features as "new" outside of announcements/release notes. - Don't make promises about uptime or oth…

If you completely disagree, keep in mind “completely” is also an adverb. Some frameworks sell simplicity (setup, maintenance) as a feature, so that adverb would be fitting. But this is just infantilizing and a lot of people (maybe a universal trait) are annoyed by that.

What? Adverbs are fine; there's no industry-wide dictum against adverbs.

I think you might be mad at something different than the principles I'm outlining here. These are accepted standards of technical documentation.

Re: Just Simply – Stop saying how simple things are in our docs

#273

Post by Aeolun »

ulizzle wrote: post #197
jonahx wrote: post #195

Earlier quoted context omitted.

It's unfortunate that this is the top comment, because the "after" samples are clear improvements. This is good old-fashioned writing advice, no different from Strunk and White's "Omit needless words" -- just tailored to developer documentation where a handful of specific needless words flourish. The main reason to remove these words is that they are fluffy, superfluous marketing speak. Do some people also find them…

It's an improvement because it cut out all the adverbs. The tone of the essay is an unmistakable virtue signal. It tries to correlate the virtue signal with quality improvement, which is either cringe or disingenuous.

If good documentation is a virtue signal, then yeah, I guess?

Re: Just Simply – Stop saying how simple things are in our docs

#275

Post by jjj123 »

yellowapple wrote: post #212
bityard wrote: post #194

Earlier quoted context omitted.

Believe me, I am all for people having thicker skins and less entitlement overall. I believe offense is generally taken rather than given, and social media's culture of constant outrage over some thing or another is a form of intellectual and moral decay. HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They…

> the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader If the author of some library was not considerably more knowledgeable than myself, then I probably wouldn't be poring over said library's documentation.

But they are writing for an audience that is not as knowledgeable, so “simply” isn’t accurate for the audience, only the writer.

Re: Just Simply – Stop saying how simple things are in our docs

#276

Post by cratermoon »

yellowapple wrote: post #212
bityard wrote: post #194

Earlier quoted context omitted.

Believe me, I am all for people having thicker skins and less entitlement overall. I believe offense is generally taken rather than given, and social media's culture of constant outrage over some thing or another is a form of intellectual and moral decay. HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They…

> the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader If the author of some library was not considerably more knowledgeable than myself, then I probably wouldn't be poring over said library's documentation.

Yes, the author of that library knows more about that library. That doesn't mean they are generally more knowledgeable than me, and in fact they may be quite ignorant about the specific problem that lead me to investigate and learn the library in the first place.

Re: Just Simply – Stop saying how simple things are in our docs

#277

Post by flockonus »

KMnO4 wrote: post #152
sametmax wrote: post #14

Earlier quoted context omitted.

The problem is a lot of it is not publicly available. E.G: I asked chat gpt to help me install Python on Ubuntu 22.04, and it failed miserably. Why? Because 22.04 is recent and many pitfalls it comes with haven't been much documented yet. And it also don't know what is never written, but implicitly known if you deal with a lot of beginners. E.G: people get utterly confused with *args and **kwargs in Python, because i…

GPT != Chat GPT, GPT-4, etc. It’s possibly to [“just simply”] train a GPT on whatever corpus you want.

For reference this is what I meant, either use some GPT-like LLM or pass on a large prompt of data previously scrapped into OpenAI GPT-4 as it currently accepts ~8k words for input in the paid plan.

Re: Just Simply – Stop saying how simple things are in our docs

#278

Post by vuciv1 »

apricot wrote: post #123

As a math professor, I had an epiphany about the word "easily" several years ago. In my course notes, I used that word to mean "I guarantee you don't need any additional ideas here, just do the obvious thing." Nothing more was meant. But I realized that many students either didn't think the obvious thing was really that obvious, or maybe realized it but were reticent to follow that path because it invoved some tediou…

I just want to say thank you for doing this. Please tell your community to do this too. I really struggled hearing such things in college.

It’s crazy to say, but I think not hearing what was “obvious” would have helped me excel more in my classes.

Re: Just Simply – Stop saying how simple things are in our docs

#279

Post by ulizzle »

spondylosaurus wrote: post #272
ulizzle wrote: post #271

Earlier quoted context omitted.

If you completely disagree, keep in mind “completely” is also an adverb. Some frameworks sell simplicity (setup, maintenance) as a feature, so that adverb would be fitting. But this is just infantilizing and a lot of people (maybe a universal trait) are annoyed by that.

What? Adverbs are fine; there's no industry-wide dictum against adverbs. I think you might be mad at something different than the principles I'm outlining here. These are accepted standards of technical documentation.

This is basic English grammar, something you should have learned in grade school.

Re: Just Simply – Stop saying how simple things are in our docs

#280

Post by ulizzle »

Aeolun wrote: post #273
ulizzle wrote: post #197

Earlier quoted context omitted.

It's an improvement because it cut out all the adverbs. The tone of the essay is an unmistakable virtue signal. It tries to correlate the virtue signal with quality improvement, which is either cringe or disingenuous.

If good documentation is a virtue signal, then yeah, I guess?

This post is a shallow public display of faux moral superiority from the language police.

I miss Linus Torvald's legendary snark and the epic flame wars of yesteryears.

Post reply on HN