6 ms·

Using Google less for privacy reasons aside (and you should too), I’ve found that as my career has progressed, I find myself way more often reading source code

Using Google less for privacy reasons aside (and you should too), I’ve found that as my career has progressed, I find myself way more often reading source code and the base documentation. Or in the case of JavaScript and CSS usually the W3 spec is the clearest source; not only is it straight from the horse’s mouth (more accurate), but it really isn’t overly technical with use cases and examples, and most importantly it displays the types of the inputs and outputs.

post-it 5y ago
I still use Google to search the documentation more easily. The Python docs are usually in the top three results if you search for "python typeddict" or whatever.
- patrickthebold 5y ago
  I always felt the official docs to be quite low in the rankings. For some reason python always has tons of tutorials for every possible situation, and those seem to bury the docs. Also the official docs are some too verbose and still don't have the detail I'm after. Maybe my second point is the reason for the first.
  - notreallyserio 5y ago
    I often end up getting results only applicable to python 2. I really dislike that they changed the language so much without ensuring backwards compatibility or changing the name.
    - dotancohen 5y ago
      Add "Python 3" (in quotes) to your google queries. In short time Google will figure it out and start sending you to Python 3 tutorials and docs. In fact, I think that's the default now. Google may have associated you with Python 2, but I'm getting almost all Python 3 results for any search Python related. You can also filter by time, but that's less useful because Python 2.7 pushed the end of life date so far back.
      - notreallyserio 5y ago
        Unfortunately a while back Google deprecated the use of quotes to indicate a "must" constraint. But it does still help somewhat.
        genewitch 5y ago
        My biggest gripe about technology in general is getting used to how something works, and then, for no reason at all (apparently) it just gets changed. Google does this because a team wants to make a name so they do a retool or redesign, it is a line item on a budget sheet and a metric for bonuses or whatever. Users be damned. I've taken to freezing certain servers and never updating them just to fight back against this. I'm tired of breaking changes every few weeks. I'm tired of learning where an option was hid in this update, only to have it moved in the next one, and the next. As an industry, shame should be wielded to prevent this. Microsoft was never held accountable for their transgressions with excel and Word. It really opened the gates for every other development house to do the same thing, and now, a decade and a half later...
gentleman11 5y ago
Depends on the source code and docs. Some projects have great docs, others have almost none and the learning process verges on “oral tradition”
- xmprt 5y ago
  I agree. With Javascript projects and frameworks, documentation can be extremely hit or miss in a way that I don't experience with other language like Python, Java, or Go.
- deleted 5y ago
  [deleted]
- Mathnerd314 5y ago
  I think the idea is that, as you get good at spelunking through source code, it becomes faster to find the answer in the source than to do anything else. E.g. I was wondering how division worked in Java, and right after searching for "ArithmeticException" in openjdk I ended up looking at HotSpot's implementation of div. Turns out (based on a source code comment) that it's defined in the JVM spec, but how would I have known that? Some codebases don't have source available, e.g. Windows, so there I guess one would use the docs.
deleted 5y ago
[deleted]
greatpostman 5y ago
Yup! For some reason I can more easily understand raw documentation and API spec. When I first started it felt more like gibberish
- alpaca128 5y ago
  For me it's the exact opposite. Documentation - especially auto-generated one - immediately makes me feel lost. I don't know where to start and when I just read it by itself my brain shuts off within minutes. The only way I can use documentation is by using it as reference alongside a project I'm working on, that's why examples are one of the most important factors for me. But I also have to say - better no examples than misleading, outdated ones. And please for dog's sake don't link to a site that requires registering an account to read nothing more than "further example" code snippets that turn out to be the same outdated examples with different variable names.
  - greatpostman 5y ago
    Right but I used to feel the same way. After years of programming, raw api spec and documentation started making sense. And I found that the answers I needed were more often than not in there
Waterluvian 5y ago
This got me thinking: I regularly read source. And one of my pet peeves with TypeScript is that I will click on a type and have to walk half a dozen types deep to understand what it is. Because the library has sensibly abstracted types to be DRY and whatnot. What I want is a type flattener that I can point at a type and it basically links it all so I see a raw type in all its verbose but complete glory.
- Jach 5y ago
  I still think this is a great appeal of Clojure(Script), you often work with the "flat" "just data" representations directly. From https://youtu.be/VSdnJDO-xdg?t=3000 https://youtu.be/VSdnJDO-xdg?t=3000 (transcript: https://github.com/matthiasn/talk-transcripts/blob/master/Hickey_Rich/ClojureMadeSimple.md https://github.com/matthiasn/talk-transcripts/blob/master/Hi...): Example - HttpServletRequest getAsyncContext, getAttribute, getAttributeNames, getCharacterEncoding, getContentLength, getContentType, getDispatcherType, getInputStream, getLocalAddr, getLocale, getLocales, getLocalName, getLocalPort, getParameter, getParameterMap, getParameterNames, getParameterValues, getProtocol, getReader, getRealPath, getRemoteAddr, getRemoteHost, getRemotePort, getRequestDispatcher, getScheme, getServerName, getServerPort, getServletContext, isAsyncStarted, isAsyncSupported, isSecure, removeAttribute, setAttribute, setCharacterEncoding, startAsync, startAsync... getHeader, getHeaderNames, getHeaders, getIntHeader... "How many maps?" Vs. In Clojure, Just Use Maps {:remote-addr "127.0.0.1", :scheme :http, :query-params {"somekey" "somevalue"}, :form-params {}, :request-method :get, :query-string "somekey=somevalue", :content-type nil, :uri "/foobaz", :server-name "localhost", :params {"somekey" "somevalue"}, :headers {"accept-encoding" "gzip, deflate", "connection" "close", "user-agent" "Apache-HttpClient/4.1.2 (java 1.5)", "content-length" "0", "host" "localhost:8383"}, :content-length 0, :server-port 8383, :character-encoding nil} "In Clojure, we just use maps. This stuff came over a wire in HTTP, as text. How did we turn it into this [the Java]?"
  - Sinidir 5y ago
    This will never cease to produce laughter in me :)
wolverine876 5y ago
> I find myself way more often reading source code and the base documentation. Yes, search engine results are for amateurs (except for finding the source, spec, base documentation, etc.). If you are serious, hold yourself and your learning to higher standards. It's also faster to read the serious sources: They are much more dense and complete, requiring less searching around and accumulation of stuff, much more to the point, more authoritative and accurate, and IME more clear (I think because clear writing requires deep understanding and clear thinking, which is much more likely to be had by the dev who wrote the code or the experts writing the spec, than blogs, reddit, or even HN commenters). You'll find that most of the online forum/blog authors don't actually know what they are talking about (and that many of your peers have big holes or misunderstandings).
- klodolph 5y ago
  > Yes, search engine results are for amatuers... I don't think that's accurate. Like the gp, I find myself relying more and more on reading the source and reading specs (WhatWG, RFCs, etc). However, search engine results are still incredibly valuable.
- gizmo385 5y ago
  > Yes, search engine results are for amateurs (except for finding the source, spec, base documentation, etc.). If you are serious, hold yourself and your learning to higher standards. This is exceptionally gatekeepy and predicated on the assumption that everyone learns or consumes knowledge in the same way you do, which is just not true. We already work in a profession that has issues with gatekeeping - I think we should avoid exacerbating that.
  - dotancohen 5y ago
    > We already work in a profession that has issues with gatekeeping - I think we should avoid exacerbating that. Why? Law and Medicine are gatekept fields, the minimum bar is essential for providing such sensitive services. With all the security issues - never mind accessibility - I think that professional software development should be gatekept. Hobbist software development - where many of us started - should of course have welcoming arms to new members. I wonder how the Law and Medicine fields would cope with hobbist communities.
Spivak 5y ago
I've been gravitating toward Sourcegraph a lot more in leu of documentation. You really can't do much better than finding real life examples of how some library is used.

post-it 5y ago

I still use Google to search the documentation more easily. The Python docs are usually in the top three results if you search for "python typeddict" or whatever.

patrickthebold 5y ago
I always felt the official docs to be quite low in the rankings. For some reason python always has tons of tutorials for every possible situation, and those seem to bury the docs. Also the official docs are some too verbose and still don't have the detail I'm after. Maybe my second point is the reason for the first.
- notreallyserio 5y ago
  I often end up getting results only applicable to python 2. I really dislike that they changed the language so much without ensuring backwards compatibility or changing the name.
  - dotancohen 5y ago
    Add "Python 3" (in quotes) to your google queries. In short time Google will figure it out and start sending you to Python 3 tutorials and docs. In fact, I think that's the default now. Google may have associated you with Python 2, but I'm getting almost all Python 3 results for any search Python related. You can also filter by time, but that's less useful because Python 2.7 pushed the end of life date so far back.
    - notreallyserio 5y ago
      Unfortunately a while back Google deprecated the use of quotes to indicate a "must" constraint. But it does still help somewhat.
      - genewitch 5y ago
        My biggest gripe about technology in general is getting used to how something works, and then, for no reason at all (apparently) it just gets changed. Google does this because a team wants to make a name so they do a retool or redesign, it is a line item on a budget sheet and a metric for bonuses or whatever. Users be damned. I've taken to freezing certain servers and never updating them just to fight back against this. I'm tired of breaking changes every few weeks. I'm tired of learning where an option was hid in this update, only to have it moved in the next one, and the next. As an industry, shame should be wielded to prevent this. Microsoft was never held accountable for their transgressions with excel and Word. It really opened the gates for every other development house to do the same thing, and now, a decade and a half later...

gentleman11 5y ago

Depends on the source code and docs. Some projects have great docs, others have almost none and the learning process verges on “oral tradition”

xmprt 5y ago
I agree. With Javascript projects and frameworks, documentation can be extremely hit or miss in a way that I don't experience with other language like Python, Java, or Go.
deleted 5y ago
[deleted]
Mathnerd314 5y ago
I think the idea is that, as you get good at spelunking through source code, it becomes faster to find the answer in the source than to do anything else. E.g. I was wondering how division worked in Java, and right after searching for "ArithmeticException" in openjdk I ended up looking at HotSpot's implementation of div. Turns out (based on a source code comment) that it's defined in the JVM spec, but how would I have known that? Some codebases don't have source available, e.g. Windows, so there I guess one would use the docs.

deleted 5y ago

[deleted]

greatpostman 5y ago

Yup! For some reason I can more easily understand raw documentation and API spec. When I first started it felt more like gibberish

alpaca128 5y ago
For me it's the exact opposite. Documentation - especially auto-generated one - immediately makes me feel lost. I don't know where to start and when I just read it by itself my brain shuts off within minutes. The only way I can use documentation is by using it as reference alongside a project I'm working on, that's why examples are one of the most important factors for me. But I also have to say - better no examples than misleading, outdated ones. And please for dog's sake don't link to a site that requires registering an account to read nothing more than "further example" code snippets that turn out to be the same outdated examples with different variable names.
- greatpostman 5y ago
  Right but I used to feel the same way. After years of programming, raw api spec and documentation started making sense. And I found that the answers I needed were more often than not in there

Waterluvian 5y ago

This got me thinking: I regularly read source. And one of my pet peeves with TypeScript is that I will click on a type and have to walk half a dozen types deep to understand what it is. Because the library has sensibly abstracted types to be DRY and whatnot. What I want is a type flattener that I can point at a type and it basically links it all so I see a raw type in all its verbose but complete glory.

Jach 5y ago
I still think this is a great appeal of Clojure(Script), you often work with the "flat" "just data" representations directly. From https://youtu.be/VSdnJDO-xdg?t=3000 https://youtu.be/VSdnJDO-xdg?t=3000 (transcript: https://github.com/matthiasn/talk-transcripts/blob/master/Hickey_Rich/ClojureMadeSimple.md https://github.com/matthiasn/talk-transcripts/blob/master/Hi...): Example - HttpServletRequest getAsyncContext, getAttribute, getAttributeNames, getCharacterEncoding, getContentLength, getContentType, getDispatcherType, getInputStream, getLocalAddr, getLocale, getLocales, getLocalName, getLocalPort, getParameter, getParameterMap, getParameterNames, getParameterValues, getProtocol, getReader, getRealPath, getRemoteAddr, getRemoteHost, getRemotePort, getRequestDispatcher, getScheme, getServerName, getServerPort, getServletContext, isAsyncStarted, isAsyncSupported, isSecure, removeAttribute, setAttribute, setCharacterEncoding, startAsync, startAsync... getHeader, getHeaderNames, getHeaders, getIntHeader... "How many maps?" Vs. In Clojure, Just Use Maps {:remote-addr "127.0.0.1", :scheme :http, :query-params {"somekey" "somevalue"}, :form-params {}, :request-method :get, :query-string "somekey=somevalue", :content-type nil, :uri "/foobaz", :server-name "localhost", :params {"somekey" "somevalue"}, :headers {"accept-encoding" "gzip, deflate", "connection" "close", "user-agent" "Apache-HttpClient/4.1.2 (java 1.5)", "content-length" "0", "host" "localhost:8383"}, :content-length 0, :server-port 8383, :character-encoding nil} "In Clojure, we just use maps. This stuff came over a wire in HTTP, as text. How did we turn it into this [the Java]?"
- Sinidir 5y ago
  This will never cease to produce laughter in me :)

wolverine876 5y ago

> I find myself way more often reading source code and the base documentation. Yes, search engine results are for amateurs (except for finding the source, spec, base documentation, etc.). If you are serious, hold yourself and your learning to higher standards. It's also faster to read the serious sources: They are much more dense and complete, requiring less searching around and accumulation of stuff, much more to the point, more authoritative and accurate, and IME more clear (I think because clear writing requires deep understanding and clear thinking, which is much more likely to be had by the dev who wrote the code or the experts writing the spec, than blogs, reddit, or even HN commenters). You'll find that most of the online forum/blog authors don't actually know what they are talking about (and that many of your peers have big holes or misunderstandings).

klodolph 5y ago
> Yes, search engine results are for amatuers... I don't think that's accurate. Like the gp, I find myself relying more and more on reading the source and reading specs (WhatWG, RFCs, etc). However, search engine results are still incredibly valuable.
gizmo385 5y ago
> Yes, search engine results are for amateurs (except for finding the source, spec, base documentation, etc.). If you are serious, hold yourself and your learning to higher standards. This is exceptionally gatekeepy and predicated on the assumption that everyone learns or consumes knowledge in the same way you do, which is just not true. We already work in a profession that has issues with gatekeeping - I think we should avoid exacerbating that.
- dotancohen 5y ago
  > We already work in a profession that has issues with gatekeeping - I think we should avoid exacerbating that. Why? Law and Medicine are gatekept fields, the minimum bar is essential for providing such sensitive services. With all the security issues - never mind accessibility - I think that professional software development should be gatekept. Hobbist software development - where many of us started - should of course have welcoming arms to new members. I wonder how the Law and Medicine fields would cope with hobbist communities.

Spivak 5y ago

I've been gravitating toward Sourcegraph a lot more in leu of documentation. You really can't do much better than finding real life examples of how some library is used.