9 ms·

I would not say coding is more fun today. There is more stuff available, true, but the quality of documentation is abysmal compared to what we used to have befo

by sklogic 10y ago

I would not say coding is more fun today. There is more stuff available, true, but the quality of documentation is abysmal compared to what we used to have before. Also, far more needless layers in between hardware and your code. It is annoying. I want to go back to my cosy VAX/VMS environment.

bluedino 10y ago
>> but the quality of documentation is abysmal compared to what we used to have It is, however, more accessible and easily searchable. And also basically free. Many programmers have never bought or own a book related to programming - they learned from all online sources. >> layers in between hardware and your code. It is annoying. But it's so much more convenient. In the old days you had to learn all about your graphics card, your printer, your sound card, you'd need a certain driver for your modem or network card... Now everything is abstracted and easy to use.
- mathgeek 10y ago
  > Many programmers have never bought or own a book related to programming - they learned from all online sources. I wonder what the effect of this has been on overall quality of code for this subset. I know that while I've learned more from online sources than books (whether physical or electronic), the lessons I have learned from books are overall above the average quality of all my sources.
  - nilved 10y ago
    I highly doubt there is any difference, since the only difference is the medium. If a book is published online, it's still a book.
    - andrew3726 10y ago
      I think you're missing the point. It's not about electronic book vs physical book (If I misunterstood you, sorry and dismiss this post). It's more about the sources on the internet, I don't know many people who read complete books on the computer but rather just read relevant sections somewhere online. While this isn't bad per se, you often miss important details due to different sources (and therefore different views/reader assumptions, ...).
    - sklogic 10y ago
      They tend to be very different kinds of books. A comprehensive, deep printed textbook vs. what is essentially nothing more than a tutorial or a collection of practical recipes.
      - nilved 10y ago
        Does reading _Learn You a Haskell_ online make it any less of a book? My point is that "online sources" is a superset of "books", making them incomparable.
        Jtsummers 10y ago
        No. However a lot of the things I, anecdata, find when I do a google search aren't books, but blogs and random tutorials and stackoverflow. Books, due to their published nature, tend to have a greater, more thorough, effort put into them. They are generally well laid out, usually well edited, and because people spent money on them the good ones tended to stay in the market and the bad ones tended to drop out. There's no fundamental difference (except for me, I do much better at recalling things I read from physical books than ebooks), in the source of online versus offline. But it's hard to ignore the difference in quality that tends to happen. What would be nice, and this is probably done somewhere, would be a reliable aggregator of good online documentation (whether it's an ebook version of a published text or not). Somewhere we can vet and see vetted quality sources of tutorials, manuals, etc.
        sklogic 10y ago
        This is among very few exceptions. Most of the books are still proper books (no matter if they're also available as e-books). Most of the stuff people use for learning online is far below a book quality.
    - mathgeek 10y ago
      > If a book is published online, it's still a book. reply Not really arguing the medium of actual books (which is why I specified in my previous post). More a comparison between topic-specific books and blog posts / StackOverflow.
  - TeMPOraL 10y ago
    I can tell you that the two languages I can confidently say I know well - C++ and Common Lisp - are the ones I learned from books. The rest I learned from various on-line tutorials, articles, references and sometimes from half-reading a book - and while I can code with them, I can feel my coding in them is mediocre. Hell, I feel that the generic-coding skills I have I owe mostly to books (and practice). You can't beat a book in terms of depth and undestanding. (And don't get me started on videotutorials. This is probably the least cost-effective educational medium ever invented.)
- sklogic 10y ago
  > more accessible and easily searchable Have not seen more easily searchable documentation than the DEC HELP system. > Many programmers have never bought or own a book related to programming And it's very sad. > - they learned from all online sources. Did they really learn anything? Without the books? Or they are simply trained to repeat few simple tricks over and over again? > But it's so much more convenient. I said needless layers. They're annoyance, not convenience. > In the old days you had to learn all about your graphics card We had OpenGL in the old days too. Pretty much straight from the beginning of the GPUs. > your printer, We had hardware PostScript back then. No drivers required. > Now everything is abstracted and easy to use There are piles of layers well above the device drivers now. With 90% of them being totally unnecessary.
  - ryandrake 10y ago
    If you think those layers are unnecessary, then don't use them. Create your application using assembly and syscalls. Don't forget though, version 1 needs to be done in 3 weeks...
    - sklogic 10y ago
      Good luck bypassing the unnecessary layers if your code have to run in a browser. Which is exactly an example of such an unnecessary layer (dozens of layers, actually). And JVM is not any better.
      - pjc50 10y ago
        No, the browser is a very necessary layer; it provides very effective security isolation between the internet and the windowing system. The mainframe days assumed that software was installed by the privileged admin and that users were the threat. It's now the other way round: most computers have only one user, but need to run all sorts of software that needs to be kept isolated from the system and each other.
        sklogic 10y ago
vanderZwan 10y ago
> but the quality of documentation is abysmal compared to what we used to have before Who needs documentation if we have Stack Overflow? /s Seriously, I had to learn React for my new job (not a web dev by trade), and while I don't dislike the framework (a compliment in programming land), a lot of times I had to resort to Stack Overflow for information that should have been provided by the documentation; which instead assumed I already understood how React worked, or forgot to mention that things were different in ES6, or mentioned that things were different but wasn't clear about how. The worst part is that when I complained about this to my friends they said "oh, React is one of the better documented frameworks out there". At that point I honestly wondered how has any webdeveloper has managed to stay sane during the last decade. As for fun coding with good documentation, I suggest Processing: https://processing.org/ https://processing.org/ .. good luck using that professionally though, unless you get paid for creating interactive art.
- sklogic 10y ago
  > Stack Overflow Even in this thread people suggested to write documentation straight there. It is an extremely worrying trend. > how has any webdeveloper has managed to stay sane during the last decade Did any of them really manage to stay sane? > https://processing.org/ https://processing.org/ Last time I looked at it I could not find a printable PDF reference. Is it possible to generate one? My quality threshold for documentation was always set very high, because I started my career with VMS. And DEC always had that obsession with comprehensive, concise and clean documentation on every tiniest bit they're exposing.
  - vanderZwan 10y ago
    Hmm, I'm not sure about the pdf thing, but it has a fairly small number of core features[0], which are all documented and can be browsed off-line, and searched through from within the minimalistic editor that it comes with. You could try looking at the source code of the documentation[1]. It uses PHP to render the site, although the actual documentation of the API is XML[2] [0] https://processing.org/reference/ https://processing.org/reference/ [1] https://github.com/processing/processing-docs https://github.com/processing/processing-docs [2] https://github.com/processing/processing-docs/tree/master/content/api_en https://github.com/processing/processing-docs/tree/master/co...
ysavir 10y ago
> There is more stuff available, true, but the quality of documentation is abysmal compared to what we used to have before. What did you expect? Nowadays, there is a common expectation, especially among web development libraries, for frequent updates, especially in the cases of bugs, etc. In the eyes of the people, functionality became more important than the documentation (though those people would like to claim otherwise, I'm sure). The demand is for the new code to be available ASAP. And as a result, the documentation suffers, and the implementations and details change faster than the documentation can be maintained. The emphasis of maintaining good documentation is further lessened by sources like StackOverflow, which provide the library maintainers with an excuse of "we can skip this step, since it will be covered in SO and countless blogs anyway. It's not like we're the only source of information." This is just an unfortunate symptom of the modern coding ecosystem. Good documentation requires stability and consistency, which today are discouraged in favor of flexibility and quick turnovers.
- softawre 10y ago
  > Good documentation requires stability and consistency Or a good architecture, a decent generation system, and a bit of discipline to write out the non-obvious bits that can't be generated.
- sklogic 10y ago
  Documentation should not suffer from frequent changes. It is easy to keep docstrings in sync with the implementation, they should both be visible at the same moment. Also, if 99.9% of all those "web frameworks" just die without a trace, the world will become a much better place anyway.

by sklogic 10y ago

bluedino 10y ago

>> but the quality of documentation is abysmal compared to what we used to have It is, however, more accessible and easily searchable. And also basically free. Many programmers have never bought or own a book related to programming - they learned from all online sources. >> layers in between hardware and your code. It is annoying. But it's so much more convenient. In the old days you had to learn all about your graphics card, your printer, your sound card, you'd need a certain driver for your modem or network card... Now everything is abstracted and easy to use.

mathgeek 10y ago
> Many programmers have never bought or own a book related to programming - they learned from all online sources. I wonder what the effect of this has been on overall quality of code for this subset. I know that while I've learned more from online sources than books (whether physical or electronic), the lessons I have learned from books are overall above the average quality of all my sources.
- nilved 10y ago
  I highly doubt there is any difference, since the only difference is the medium. If a book is published online, it's still a book.
  - andrew3726 10y ago
    I think you're missing the point. It's not about electronic book vs physical book (If I misunterstood you, sorry and dismiss this post). It's more about the sources on the internet, I don't know many people who read complete books on the computer but rather just read relevant sections somewhere online. While this isn't bad per se, you often miss important details due to different sources (and therefore different views/reader assumptions, ...).
  - sklogic 10y ago
    They tend to be very different kinds of books. A comprehensive, deep printed textbook vs. what is essentially nothing more than a tutorial or a collection of practical recipes.
    - nilved 10y ago
      Does reading _Learn You a Haskell_ online make it any less of a book? My point is that "online sources" is a superset of "books", making them incomparable.
      - Jtsummers 10y ago
        No. However a lot of the things I, anecdata, find when I do a google search aren't books, but blogs and random tutorials and stackoverflow. Books, due to their published nature, tend to have a greater, more thorough, effort put into them. They are generally well laid out, usually well edited, and because people spent money on them the good ones tended to stay in the market and the bad ones tended to drop out. There's no fundamental difference (except for me, I do much better at recalling things I read from physical books than ebooks), in the source of online versus offline. But it's hard to ignore the difference in quality that tends to happen. What would be nice, and this is probably done somewhere, would be a reliable aggregator of good online documentation (whether it's an ebook version of a published text or not). Somewhere we can vet and see vetted quality sources of tutorials, manuals, etc.
      - sklogic 10y ago
        This is among very few exceptions. Most of the books are still proper books (no matter if they're also available as e-books). Most of the stuff people use for learning online is far below a book quality.
  - mathgeek 10y ago
    > If a book is published online, it's still a book. reply Not really arguing the medium of actual books (which is why I specified in my previous post). More a comparison between topic-specific books and blog posts / StackOverflow.
- TeMPOraL 10y ago
  I can tell you that the two languages I can confidently say I know well - C++ and Common Lisp - are the ones I learned from books. The rest I learned from various on-line tutorials, articles, references and sometimes from half-reading a book - and while I can code with them, I can feel my coding in them is mediocre. Hell, I feel that the generic-coding skills I have I owe mostly to books (and practice). You can't beat a book in terms of depth and undestanding. (And don't get me started on videotutorials. This is probably the least cost-effective educational medium ever invented.)
sklogic 10y ago
> more accessible and easily searchable Have not seen more easily searchable documentation than the DEC HELP system. > Many programmers have never bought or own a book related to programming And it's very sad. > - they learned from all online sources. Did they really learn anything? Without the books? Or they are simply trained to repeat few simple tricks over and over again? > But it's so much more convenient. I said needless layers. They're annoyance, not convenience. > In the old days you had to learn all about your graphics card We had OpenGL in the old days too. Pretty much straight from the beginning of the GPUs. > your printer, We had hardware PostScript back then. No drivers required. > Now everything is abstracted and easy to use There are piles of layers well above the device drivers now. With 90% of them being totally unnecessary.
- ryandrake 10y ago
  If you think those layers are unnecessary, then don't use them. Create your application using assembly and syscalls. Don't forget though, version 1 needs to be done in 3 weeks...
  - sklogic 10y ago
    Good luck bypassing the unnecessary layers if your code have to run in a browser. Which is exactly an example of such an unnecessary layer (dozens of layers, actually). And JVM is not any better.
    - pjc50 10y ago
      No, the browser is a very necessary layer; it provides very effective security isolation between the internet and the windowing system. The mainframe days assumed that software was installed by the privileged admin and that users were the threat. It's now the other way round: most computers have only one user, but need to run all sorts of software that needs to be kept isolated from the system and each other.
      - sklogic 10y ago

vanderZwan 10y ago

> but the quality of documentation is abysmal compared to what we used to have before Who needs documentation if we have Stack Overflow? /s Seriously, I had to learn React for my new job (not a web dev by trade), and while I don't dislike the framework (a compliment in programming land), a lot of times I had to resort to Stack Overflow for information that should have been provided by the documentation; which instead assumed I already understood how React worked, or forgot to mention that things were different in ES6, or mentioned that things were different but wasn't clear about how. The worst part is that when I complained about this to my friends they said "oh, React is one of the better documented frameworks out there". At that point I honestly wondered how has any webdeveloper has managed to stay sane during the last decade. As for fun coding with good documentation, I suggest Processing: https://processing.org/ https://processing.org/ .. good luck using that professionally though, unless you get paid for creating interactive art.

sklogic 10y ago
> Stack Overflow Even in this thread people suggested to write documentation straight there. It is an extremely worrying trend. > how has any webdeveloper has managed to stay sane during the last decade Did any of them really manage to stay sane? > https://processing.org/ https://processing.org/ Last time I looked at it I could not find a printable PDF reference. Is it possible to generate one? My quality threshold for documentation was always set very high, because I started my career with VMS. And DEC always had that obsession with comprehensive, concise and clean documentation on every tiniest bit they're exposing.
- vanderZwan 10y ago
  Hmm, I'm not sure about the pdf thing, but it has a fairly small number of core features[0], which are all documented and can be browsed off-line, and searched through from within the minimalistic editor that it comes with. You could try looking at the source code of the documentation[1]. It uses PHP to render the site, although the actual documentation of the API is XML[2] [0] https://processing.org/reference/ https://processing.org/reference/ [1] https://github.com/processing/processing-docs https://github.com/processing/processing-docs [2] https://github.com/processing/processing-docs/tree/master/content/api_en https://github.com/processing/processing-docs/tree/master/co...

ysavir 10y ago

> There is more stuff available, true, but the quality of documentation is abysmal compared to what we used to have before. What did you expect? Nowadays, there is a common expectation, especially among web development libraries, for frequent updates, especially in the cases of bugs, etc. In the eyes of the people, functionality became more important than the documentation (though those people would like to claim otherwise, I'm sure). The demand is for the new code to be available ASAP. And as a result, the documentation suffers, and the implementations and details change faster than the documentation can be maintained. The emphasis of maintaining good documentation is further lessened by sources like StackOverflow, which provide the library maintainers with an excuse of "we can skip this step, since it will be covered in SO and countless blogs anyway. It's not like we're the only source of information." This is just an unfortunate symptom of the modern coding ecosystem. Good documentation requires stability and consistency, which today are discouraged in favor of flexibility and quick turnovers.

softawre 10y ago
> Good documentation requires stability and consistency Or a good architecture, a decent generation system, and a bit of discipline to write out the non-obvious bits that can't be generated.
sklogic 10y ago
Documentation should not suffer from frequent changes. It is easy to keep docstrings in sync with the implementation, they should both be visible at the same moment. Also, if 99.9% of all those "web frameworks" just die without a trace, the world will become a much better place anyway.