I've recently started programming again after 15 odd years doing consultancy, and I've been using php and SQL to write web servery stuff (initially) and more recently C++ on linux then java for android (and porting some C code as well), with dablings along the way into lua and bash.
My big issue with nearly all modern documentation is the total lack of information on the architecture behind the API (or whatever interface I'm using). To write effectively you must be in harmony with the software environment you are working with, but 99% of the documentation explains (in brain bending detail) that when you press the 'y' key, you get a 'y', well yes I already had that sussed guys, what I really need to know has to be teased out by reading the documentation, endless posts on stack overflow and many other places. It's all very well explaining how to make my model rotate in opengl with some guys favorite series of calls, but I want to know WHY you do it that way, 'cos without this knowledge every minor change becomes a trip into the unknown.
"how to do it" Documentation is provided as a set of incantations where a very specific recipe gives a very specific effect, but if you change the eye of frog on line 42 for eye of toad - well the results are dramtically different (assuming you live to tell the tale). I want the same sort of information I was taught in school countless years ago in science lessons about electron orbits, valency etc. which brough the periodic table to life, and meant you could predict what Molybdenum would be like because of the number of protons.
I'm on my 3rd total rewrite of an android app, 'cos I've slowly been learning how to go with the android flow because of this lack of meta information. Some time you find a few gems - in the case of android, quite often this is videos from the android team at various big events.
This is exacly the same problem I had many years ago trying to write for Windows, the API information was like most microsoft help - totally helpless. Interfaces are explained in great detail, but with almost zero information contents. I need to know WHY I would choose to use the value, and what it's effect is (particularly when combined with other values provided to other related API calls.
I can think of only a few situations where I've come across information that actually made me feel I understood what was really going on from the start, for example in the XSLT Programmer's Reference by Michael Kay (5 out of 5 for that one). The OpenGL Superbible (several authors) was also pretty good (I'll give that 4/5 - good but still resorts to incantations in many places. Oh yes "PostGIS in action" Regina O.Obe and Leo S. Hsu is pretty good too but still in the thick of that one so not sure on the final score yet.
Looks like books can still hit the right spot - unfortunately just not the ones that are supposed to document the product in question.
Of course the real problem with many API's is that the various interface calls are full of side effects and the underlying code is riddled with 'optimisations' to try and improve performance, with the result that a slight change in the use and the whole thing falls apart. Android, Windows and the various linux gui platforms all fall into this bear trap, and I suspect that it's the lack of a properly documented architecure as a guiding light for everything that happens below which is the real cause of the poor documentation.
Slashdot Mirror
My big issue with nearly all modern documentation is the total lack of information on the architecture behind the API (or whatever interface I'm using). To write effectively you must be in harmony with the software environment you are working with, but 99% of the documentation explains (in brain bending detail) that when you press the 'y' key, you get a 'y', well yes I already had that sussed guys, what I really need to know has to be teased out by reading the documentation, endless posts on stack overflow and many other places. It's all very well explaining how to make my model rotate in opengl with some guys favorite series of calls, but I want to know WHY you do it that way, 'cos without this knowledge every minor change becomes a trip into the unknown.
"how to do it" Documentation is provided as a set of incantations where a very specific recipe gives a very specific effect, but if you change the eye of frog on line 42 for eye of toad - well the results are dramtically different (assuming you live to tell the tale). I want the same sort of information I was taught in school countless years ago in science lessons about electron orbits, valency etc. which brough the periodic table to life, and meant you could predict what Molybdenum would be like because of the number of protons.
I'm on my 3rd total rewrite of an android app, 'cos I've slowly been learning how to go with the android flow because of this lack of meta information. Some time you find a few gems - in the case of android, quite often this is videos from the android team at various big events.
This is exacly the same problem I had many years ago trying to write for Windows, the API information was like most microsoft help - totally helpless. Interfaces are explained in great detail, but with almost zero information contents. I need to know WHY I would choose to use the value, and what it's effect is (particularly when combined with other values provided to other related API calls.
I can think of only a few situations where I've come across information that actually made me feel I understood what was really going on from the start, for example in the XSLT Programmer's Reference by Michael Kay (5 out of 5 for that one). The OpenGL Superbible (several authors) was also pretty good (I'll give that 4/5 - good but still resorts to incantations in many places. Oh yes "PostGIS in action" Regina O.Obe and Leo S. Hsu is pretty good too but still in the thick of that one so not sure on the final score yet.
Looks like books can still hit the right spot - unfortunately just not the ones that are supposed to document the product in question.
Of course the real problem with many API's is that the various interface calls are full of side effects and the underlying code is riddled with 'optimisations' to try and improve performance, with the result that a slight change in the use and the whole thing falls apart. Android, Windows and the various linux gui platforms all fall into this bear trap, and I suspect that it's the lack of a properly documented architecure as a guiding light for everything that happens below which is the real cause of the poor documentation.
Looks like what M$ did to nokia was just a test run before doing it to themselves