4 ms·

> Improve information, get more attention. Clickbait all the documentation! ;-)

by high_5 6y ago

tomp 6y ago
I'm not so sure... just, like, maybe put one single thought into organizing it? I still hold PHP documentation as a golden standard even though I haven't used the language in like 10 years. Everything is spelled out, and what's still unclear, there's usually a comment or two at the bottom of the page asking to clarify just that. Contrast that with Python, my current main language... not only is it badly organized as a whole (where do I find documentation for `str`? Surely there's a page... no! it's all bundled up together in "Built-in types!"), the individual pages _also_ have no sensible structure and not even a good TOC! Python's jumping between versions and deliberate refusal to back-port features doesn't help either, but that's a different topic...
- rsa25519 6y ago
  > I'm not so sure... just, like, maybe put one single thought into organizing it? Most documentation definitely needs more attention towards organization. But in my experience, organization is extremely difficult, especially because a documentation author may think of the system very differently than a new user might
cardiffspaceman 6y ago
OP should have sent an email titled, "One weird fact about the DB driver!"
- BrandoElFollito 6y ago
  And then proceed to a 37 pages long doc, where he explains the history of drivers since 1745, and repeats and repeats Advertizement above the NEXT button which keeps shifting while the page loads Little did you know that the driver is actually You have reached your free limit of 1 article per month, SUBSCRIBE HERE, but the button shifts again and now you have porn and "you have a virus" popping out everywhere And you want to leave but the back button id hijacked and you understand why the etymology of vi is an Aztec phrase for "how do I get out of this shit"

4 ms·

> Improve information, get more attention. Clickbait all the documentation! ;-)

by high_5 6y ago

> Improve information, get more attention. Clickbait all the documentation! ;-)

tomp 6y ago
I'm not so sure... just, like, maybe put one single thought into organizing it? I still hold PHP documentation as a golden standard even though I haven't used the language in like 10 years. Everything is spelled out, and what's still unclear, there's usually a comment or two at the bottom of the page asking to clarify just that. Contrast that with Python, my current main language... not only is it badly organized as a whole (where do I find documentation for `str`? Surely there's a page... no! it's all bundled up together in "Built-in types!"), the individual pages _also_ have no sensible structure and not even a good TOC! Python's jumping between versions and deliberate refusal to back-port features doesn't help either, but that's a different topic...
- rsa25519 6y ago
  > I'm not so sure... just, like, maybe put one single thought into organizing it? Most documentation definitely needs more attention towards organization. But in my experience, organization is extremely difficult, especially because a documentation author may think of the system very differently than a new user might
cardiffspaceman 6y ago
OP should have sent an email titled, "One weird fact about the DB driver!"
- BrandoElFollito 6y ago
  And then proceed to a 37 pages long doc, where he explains the history of drivers since 1745, and repeats and repeats Advertizement above the NEXT button which keeps shifting while the page loads Little did you know that the driver is actually You have reached your free limit of 1 article per month, SUBSCRIBE HERE, but the button shifts again and now you have porn and "you have a virus" popping out everywhere And you want to leave but the back button id hijacked and you understand why the etymology of vi is an Aztec phrase for "how do I get out of this shit"