431–440 of 455 posts
OPs argument is flawed. Documentation is not there to teach you from scratch. Its there to describe a projects intended behaviour under normal conditions. Often times people will cry about lacking context and expect you to basically use it for them. I would heavily recommend against that as you will end up as unpayed and burned out tech support...
OPs everything is flawed but she tries really hard.
Earlier quoted context omitted.
Or let the Junior rewrite the docs while they're scratching their head, and push an update once they've figured it out.
I'm a senior designer who often contributes to front-end code when it's convenient for my client. Fixing and updating the README when I join a new team and set up their dev environment is always extremely well-received.
Earlier quoted context omitted.
And conversely, there are languages with different words for "father's sister" and "mother's sister", and for male vs female cousins, etc.
And we don't even have to get exotic for that. My language, Danish, is just a run-of-the-mill Germanic language and those terms are "faster", "moster", "fætter", and "kusine". Some of the East Asian languages are crazy regarding terms for family members. It's like learning foreign words for plants: I just give up. I will not even attempt to learn them.
Earlier quoted context omitted.
This is why I rage against the crowd that promotes "self documenting code". There's no such thing, even if you should strive to make your code as readable as possible. But if there's a way to misinterpret it then you can bet many people will. The biggest problem is that this ends up creating so much extra work. An extra 2 seconds from the dev could save hundreds or even thousands of people hours of work. I can't tell…
This kind of bad documentation is actually way more common in teams that require doc comments for all code, which are then promptly auto-generated by the IDE and never filled with actually useful information. Self documenting code in this case would mean using a type that encodes the unit - which would have the additional benefit that the compiler or other tools can now check correct usage.
Requiring docs isn't the cause of the problem. It's the lack of enforcing quality. The difference is that you're looking at the metric and seeing Goodharts Law in action while there's nothing preventing you from going beyond the metric. That's the real issue is that metrics only take you so far. No metric can be perfectly aligned so it's up to the people who are evaluating the metrics to determine if the letter of the law is being followed or the spirit of it is. If you do the latter then yeah, maybe some functions will be left without docs but you also won't hasn't those tautological docs either. If you only care about the letter of the law then you should expect the laziest bullshit as Goodharts Law always wins out.
Stop reading too much into metrics. Metrics are only guides
Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot user…
I seem to have this problem a lot with Apple’s docs. So much of it is like Nargflargler: Flargles the narg You need to do something besides repeat the name in the definition.
Earlier quoted context omitted.
The struct is only named on the link you provided, not documented. So thanks for showing the absolute irony of it not being greatly documented, allowing people to misinterpret what it means.
Because it’s a boring enum in C, auto translated to a swift struct. And if you’re reading the documentation because you do development, then you would already know that the header files are installed on your computer and you can trivially verify that there is nothing to document because it’s just a query key.
Going off to read the header file means it isn't documented.
Earlier quoted context omitted.
good job, you missed the point
Great job, you've failed to document the point.
Sure, I will grant that someone who doesn't know what a computer is shouldn't be expected to follow a tutorial to install PostgreSQL on a headless linux server with proper security protocols in place.
The issue is more that it's extremely easy to assume someone understands what "primitive file operations" are necessary to accomplish a goal, and fail to describe what it is the user actually has to do.
Just because you understand how to navigate a file structure doesn't necessarily mean you have the domain knowledge necessary to make leaps that are frequently present in tutorials.