Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Not sure if it's quite what you're after, or if it's as good as it used to be, but php.net's documentation was PHENOMENAL back in the day when I was just getting started (~20 years ago).

Worst: My god, look at Apple. Where's the documentation on MacOS?!

EDIT: One thing I would suggest is to find a balance between skimmable documentation (nobody READS anymore, we don't have time or patience for that) and explanation (extracted structure/data types alone aren't nearly enough). Also, code samples! Code samples all the way! These are very helpful particularly for people that don't speak English as their native language. It's one thing to skim some English documentation and not quite "get it", but a code sample illustrating usage in a simple context can go much, much further.



I would like to add: biggest things about code samples: 1) Use every parameter / return in the example. There is no good reason to put (_, speed) = myFunc() because what is the first returned value?

2) Don't name the input parameters the exact same as the variables, even though it reads nicer Class Pet: func pet(pet)

pet=Dog Pet.pet(pet) <----- whyyyyyyyyy




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: