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

291–299 of 299 posts

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

#291

Post by TheCoelacanth »

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.

That's fine, but put your marketing copy in your marketing, not in your docs.

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

#294

Post by abtinf »

kazinator wrote: post #266
abtinf wrote: post #49

Earlier quoted context omitted.

In English, the math jargon term “simplifies to” means roughly “is equivalent to this less complex form”. It does not connote difficulty.

It absolutely denotes difficulty. E.g. more machine cycles are needed to traverse the original expression tree that has more nodes.

You dropped the context of the discussion. We aren’t talking about machines, but humans.

That is a different usage of the word “difficulty”, meaning something requiring more work to achieve an outcome, but that is not the relevant meaning in this context.

In the context of this discussion, “difficulty” is being used to describe the level of significant and sustained focused mental effort to grasp and integrate a new concept into one’s existing body of knowledge.

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

#295

Post by tremon »

hooverd wrote: post #201
tremon wrote: post #128

Earlier quoted context omitted.

and should ask for help By... reading the documentation, for example?

Simply find the relevant thread in the mailing list. Or just watch one of the author's talks.

> Simply

I see what you did there :)

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

#296

Post by peoplefromibiza »

throwawaaarrgh wrote: post #270
peoplefromibiza wrote: post #118

Earlier quoted context omitted.

> YouTube tutorial that starts from scratch has a very simple and obvious reason why it starts there what's the reason in your opinion? Because in my opinion a programming tutorial that starts from installibg the IDE is like a recipe tutorial that starts from how to use a gas stove. it should be two different tutorials, at least It is clearly important to understand how an IDE works, but that's the kind of knowledge…

One of the things I do for a living is write documentation. I have the privilege of supporting a lot of different types of users. And within each type of user, there is variability. For every document I write, there are always a couple people for whom my document fails. It's not because they're stupid, or because I am. It's because communication is hard, and different perspectives change how information is processed.…

> The YouTube video that shows you installing the IDE is superior to one that doesn't

I disagree.

That's assuming that your time is infinite, the user time is infinite and you are writing a tutorial about everything.

It's usually not the case, the best documentation I have found is the kind that focus on what it is about and only that.

It doesn't imply that an introduction is not necessary, it implies that you will talk about what's in the title of the document and only that. You have to assume a certain level of knowledge, you gotta stop somewhere and say "they must know this already or this is not for them" otherwise any documentation should include a chapter on how to download the software you are about to install and how to, why not?, connect to a WI-FI network. "A tutorial that talks about it is superior to one that doesn't" isn't it?

YouTube videos do that because the algorithm rewards longer videos, tech writers to that because it makes the final document larger and larger is always better than smaller, if you are paid for the words you write.

The laziest documentation I have found is the one that starts from the origin of the universe and it only resolves in the last 5 paragraphs, "drawing an howl" style, even though it should only be about drawing the damn howl.

One infamous example is Coursera coursers, each one of them presents the same exact intros, like if it's Java or Scala, they start on how to install Intellij Idea and the first assignment is compile a project and send it to show you understood how it is done. Except the course is called something like "Writing highly concurrent distributed systems in Scala", it is marked as an advanced specialization and it makes no sense to take it if you don't know how to install an IDE. But even assuming it happens, it could be easily solved by an FAQ. And BTW you have to complete the first assignment even if this is the nth course you're taking on the subject, you already installed Intellij, already compiled a project and already completed the assignment n minus 1 other times.

Do you also believe that teaching people how to drive a car should start from how to buy one?

> what you will find is the user will run into a problem that the two separate documents didn't consider when taken together.

the opposite is usually true in my experience.

You will find that most of the times the people that are actually interested in the documentation, will be much better off with a more succinct version of the same document.

> If you start getting fancy and make 50 different documents for different steps, because "logically" that makes more sense,

Nobody said 50 different documents. Just separated the "tools setup" from the rest of the documentation or put it in an appendices at the end.

The "setup" section in most Github repos are very welcome, if they are in the in the form

  * do this
  * do that
  * run `docker run ... -p ...`
if they were of the form "Docker is an open source platform that enables developers to build, deploy, run, update and manage containers ..." and then went on with the instructions on how to install it on every single platform, I would close the browser's tab and look somewhere else. Just refer to another document that explains it all in details for those who might need it and be done with it.

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

#297

Post by jodrellblank »

shri_krishna wrote: post #213
jodrellblank wrote: post #207

Earlier quoted context omitted.

The left: "X change would be better because Y". The right, having a meltdown about it: "I'm superior, you're snowflakes, you're pathetic babies, you're weak, I'm a real adult, I'm not afraid, you're triggered by everything, blah blah ". Why does this happen? Why are you so insecure that suggesting a way for documentation to be made clearer makes you conjour up a fantasy about an imaginary group of people who can't le…

> The left: "X change would be better because Y". > The right, having a meltdown about it: "I'm superior, you're snowflakes, you're pathetic babies, you're weak, I'm a real adult, I'm not afraid, you're triggered by everything, blah blah". Bad analogy. It literally applies to the article itself. The left: Mailers are really just another way to render a view The right, having a meltdown over "just" and "simply": Remov…

> "No where did I say anyone is inferior to me? I said some are snowflakes"

There, where you insult people. It seems clear from the context that you are not including yourself in the snowflakes, instead including yourself as superior to the snowflakes. When someone calls someone else stupid or slow or weak or whiner, it's usually in the context of "and I'm better".

> "get offended by the most random thing imaginable and there is no obligation to cater to everyone's whims and fancies."

Whenever you can split the political divide into compassion/cruelty, it's the Left encouraging or supporting compassion and the right siding with "fuck you, got mine". Who, for example, said you had an 'obligation' to write in a particular way? Instead of the article turning into "yeah, okay, no skin off my nose to remove those words" or "I prefer it this way, feel free to write your own version your way", it turns into namecalling, ego protecting, self-defense.

> "The right, having a meltdown over "just" and "simply": Remove "just" and "simply" else it will ruin my flow of thought"

Saying "X is bad because I trip over it" is not melting down. Saying "you trip over X because you're weak and clumsy and a whining crybaby, you'd never survive an Antartic exploration expedition like a True Scotsman, I have no obligation to do what you demand, I don't need to because I don't trip over X" is. It doesn't engage with the actual issue, doesn't consider whether the change has merit more or less than it costs, doesn't reply about why the style is clearer/better/more fun/more personal, it's a reply to show a) the author is in with the tougher more superior crowd who don't need it, b) the requestor is pathetic.

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

#298

Post by runeks »

wdfx wrote: post #38
sametmax wrote: post #3

It's a more and more popular opinion: - Why not tell people to "simply" use pyenv, poetry or anaconda ( https://bitecode.substack.com/p/why-not-tell-people-to-simpl... ) - Don’t use the word ‘simply’ ( https://jameshfisher.com/2017/02/22/dont-use-simply/ ) - Stop using ‘simply’ in tech instructions ( https://www.parkersoftware.com/blog/stop-using-simply-in-tec... ) - Don’t say “simply” in your documentation ( https:/…

Similarly, one should never state that something is "obvious". I catch myself sometimes starting a sentence with "Obviously," and usually stop myself at that point and restart.

> Similarly, one should never state that something is "obvious".

Agreed.

Logically speaking, if something is obvious, why are you wasting time stating it?

Either you've wasted everyone's time or it wasn't obvious.

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

#299

Post by dorkwood »

codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

I suppose it depends whether you’re writing documentation that you want people to read or not.

I often have to write documentation for non-technical people, and if they don’t understand it or they find it too discouraging to follow, it makes my job harder.

I can yell and shout all day about how they should just get a thicker skin and study my words more thoroughly, but it won’t change human nature. Eventually you need to stop wishing humanity was different, and accept humanity as it is.

Post reply on HN