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:
.. good luck using that professionally though, unless you get paid for creating interactive art.
well, consider the ruby language: it is implementation-defined(!).
i got a Rails job without knowing any of Ruby beforehand (and the other party was aware of this). i made myself comfortable in the office and asked: so where's the Ruby manual? they said, "ruby-doc.org". "that's just the API docs, where's the language reference?" i asked. "there's none. maybe you could use the Bison grammar from the MRI source..." "???"
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?
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.
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/
[1] https://github.com/processing/processing-docs
[2] https://github.com/processing/processing-docs/tree/master/co...
Who said we stayed sane?
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.
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.
Also, if 99.9% of all those "web frameworks" just die without a trace, the world will become a much better place anyway.
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.
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.
(And don't get me started on videotutorials. This is probably the least cost-effective educational medium ever invented.)
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.
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.
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.
In the end, it's still 40 hours a week and the pay is still good :)
Someone missed out on the early PC days ;-) An example of what I'm thinking: Standardized-ish PC hardware (CGA, EGA, VGA, et al) might be abstracted by the programming language's libraries, but devs often reached below the abstraction, manually twiddling registers in the hardware. There weren't really standardized "drivers" for a lot of the available hardware.
OpenGL was opened in 1992, but it was only toward the late 90s that any (consumer-level) GPUs actually implemented it.
My apologies if you're mostly talking about non-consumer hardware.
I ignored PCs altogether. They were useless toys back then.
We had SGIs, so who cared about PCs?
> devs often reached below the abstraction, manually twiddling registers in the hardware
And we're still doing it, nothing changed. Want performance and control - go low level. Want uniform APIs - use what your vendors are trying to feed you with.
> you're mostly talking about non-consumer hardware
An SGI station is still a kind of a "consumer" hardware.
Who's "we"? If you mean that they existed, then OK, I can't argue that. I've never known anyone that had one, but hundreds who had PC-level hardware.
>And we're still doing it, nothing changed. Want performance and control - go low level.
Low-level has changed significantly in meaning. Now maybe someone would try to go through the driver instead of the higher-level API, but no one's going to do direct register writes. Modern hardware isn't usable at that level.
> An SGI station is still a kind of a "consumer" hardware.
Not a mainstream one by most measures, which is what I was trying to get at.
We as an industry in general.
> Low-level has changed significantly in meaning
Not that much, actually, just shifted to the other domains.
> but no one's going to do direct register writes.
You'd be surprised. People even do bit-banging now (could you imagine bit-banging a VGA port directly in the past?).
> Modern hardware isn't usable at that level.
Is something like VC4 GPU modern enough? People do work with it on a very low level, thanks to the open specs. See this for example: https://github.com/mn416/QPULib
Actually, all the modern GPUs are getting simpler and more unifirm, so it's getting easier to hack them on a low level.
And JVM is not any better.
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.
Effective security isolation is a necessary layer. Browsers are one option to provide that, but there are others. They also provide ways to fetch, run, and interface with cross-platform, highly-efficient code from all over the world. That's both a blessing and a curse.
When I think about the volume of other people's software that we run while doing things online, I wonder how much of it is actually directly related to whatever I'm trying to do, and how much is incidental, unnecessary overhead.
Sort of interesting to think about this now, in the context of web apps and the recent Android instant apps.
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.