I'm a sick to fucking death of reading 'documentation' by developers who assume you know everything they did at the time of writing and so leave out 90% of the context that would make the documentation make any sense.

Listen to me. If you are writing instructions on how to do something you have 2 options.

1. Write steps that are so detailed a person who has never touched the system could do them
2. Give enough information for a person who has never touched the system to work it out for themselves.

NOT. LET ME REPEAT MYSELF. NOT: 3. Give some half assed info that assumes you had already been working on the system and practically knew everything anyway.

If I had already been working in this area I WOULDNT NEED THE FUCKING DOCUMENTATION TO BEGIN WITH.

Hah, yea, impossible.

I once wrote a manual for our product. It included references to docker. They did not know how to use docker.

I instead wrote a how-to start, arguing that docker explanations did have no place in our software's manual. So, I wrote a how to.

They now expected me to explain step by step from where I got those commands. Ugh... The docker manual? I linked it. Still not good enough.

There is a sweet spot between a documentation. I do not need to have explained what a spin lock is, not even in a lock library. That's what other books are for. And even less on a library that just suggest that something could be combined with a spin lock.

But, I have often found myself lost, not knowing what the author wanted from me.

So, yea, being absolutely thorough is bullshit. Yet... How thorough? No one came up with a reproducible definition, yet. Just subjective opinions. Make a metric, first.

Have you been reading the google docs as well? Here is a quick start using 5-year-old syntax and 2 deprecated versions behind, oh you want actual docs, here is a list of functions instead

Hey, go on and judge my README for my NPM package.

https://npmjs.com/package/...

Go and tell me about your opinions, I'm open to constructive criticism.

@Ranchonyx Mentioning features and common error situations/limitations nice.

The imports are a bit weird, with the description I was expecting :

import mjson from "@ranchonyx/mjson"

mjson.parseSync /mjson.parse (similar to FS api)

Therefore, it's good you show the whole input-process-output cycle

Pretty much what I'd want for a "small" library like this, the only thing that would be missing would be the list of supported config/options, but it doesn't look like you have any

tbh if you write too much context unsucinctly I'm just not going to read it

@BordedDev google docs send you down 12 pages and none of those pages have what you're looking for 🤪

skill issue

@jestdotty Literally had that happen today, since they deprecated google/gapi auth now how you have to use firebase from what I can tell but how do you use that token to do a rest call (to trigger a pubsub from the browser) that used to just work.

Still haven't found the answer, will just proxy it through the backend on monday I think

@Ranchonyx I don't see the practical use neither, but it's still cool stuff anyway. I hope you take this critisism like a man.

For me that's the big issue writing docs. Not knowing how much detail I have to give. I mean, you've made a basic python script, even if it is targetted to beginners, should you include setting up the python environment? Best is probably to do a notice to a python environment setup tutorial and not going in depth about it I guess.

At the beginning, the audience should be clear. But with a step by step a full tutorial, you're probably never wrong. It can be used by everyone and it's not that much work most of time. If it is, maybe the application could be working simpler.

Tutorial for creating a bot for my new chat app will be around ten lines and a code snippet. That's all.