Re:Ask HN: What is example of good documentation in your opi...
by bakugo on Sunday November 20, 2022 @12:55PM
(#33683322)
I'll have to disagree. Many things about it are a constant source of annoyance for me, such as the fact that function arguments and return types aren't listed in a standard format with a short description of each and instead they expect you to read the entire (often quite large) paragraph of text below each function to find that information, and the fact that a lot of information isn't found in the page you'd expect it to be in (for example, the methods available for the list type aren't in the Built-in Types page even though lists are mentioned there, nor in its own dedicated list page, but are instead in a "More on Lists" section in the Data Structures page which apparently isn't linked in the types page at all)
[ Parent
| on HN ]
Re:Ask HN: What is example of good documentation in your opi...
by thiht on Sunday November 20, 2022 @02:47PM
(#33684544)
Completely agree. The Python docs are almost unreadable to me. Every time I’m looking for something (a function parameter, example usage, etc.) it’s the same:
- I Google it
- I look for the official docs page (usually 5th or 6th result)
- I tried to find my answer but don’t understand the organization and cannot find the correct keywords to Ctrl-F
- I go back to my Google search frustrated and try to find a suitable StackOverflow answer instead
In comparison with Go the official docs are usually the first or second Google results and the docs are easy to navigate and understand.