You're being sarcastic, but several years ago I was living in Japan, and saw something awfully close to what you describe.
The government in the US at the time was trying to figure out what to do with the settlement of the Big Tobacco lawsuit, and many states were putting together anti-smoking campaigns. I don't know if you've ever been to Japan, but folks there are big smokers.
So some mid-level bureaucrat in the Ministry of Health and Welfare was interviewed on the evening news, and asked if the government in Japan would also be engaging in anti-smoking efforts. With a level of candour unthinkable on the other side of the pond, this fellow plainly stated that no, Japan's government would not, because smoking would help reduce the aging population and thereby limit the ultimate public expenditures required to care for a large elderly population.
Reading all the responses here, it sure looks like different folks have widely different reactions to caffeine -- no big surprise, but big medical in the media has yet to understand that everyone's a bit different, and no, one size definitely does not fit all.
Anyway, the one time in my life that I *have* hallucinated was after drinking far too much of the witches' brew coffee at a local greasy spoon, the dregs of the pot that had been sitting on the burner all afternoon and had simmered down to sludge by just before closing time when we usually showed up. I had maybe half a dozen cups of that, and my friend and I were having a ball talking about all sorts of wackiness. Once the diner kicked us out to close, we went driving on back country roads like usual to catch some air in some places and continue talking.
Aside from general perceptual distortions, every time we passed a Mobil gas station, I felt like I was getting sucked into the red "O" in the signs.
All the winding roads soon made me carsick though, and we pulled over. By that point it was around 2AM or so. The local sherriff pulled over a few minutes later -- "All right boys, whaddya been drinking?"
Both of us: "Coffee! Coffeecoffeecoffeesir, toomuchcoffee!" Sherriff: "Huh... well, I'm'a have to give you a breathalyzer test."
(given the look on the sherriff's face, we must have scored negative values)
"Boys,... It's 2AM. Go home."
But yeah, the next day was unpleasant, even without the M&Ms.:-P
Can you get me in touch with these people you're advising? I could certainly use some free IT equipment.
No really, I'm serious -- if you know of folks throwing out perfectly functional computers solely because of virus infections, I'd love to have a few of their machines. Heck, they're worth something just for hobbyist spare parts, if nothing else.:)
Wow, some fun, interesting, and smart goings-on here at Slashdot! Oh yeah, that's why I still come here...:)
As an aside to the debate, I don't see those two as utility-less. Bear in mind that utility is a really broad requirement, and "providing entertainment" or "reducing embarrassment" are perfectly legitimate uses.
Forgive me, I should have been more explicit. I don't consider the ideas claimed to be utility-less, but rather the patents themselves, w.r.t. any advancements -- both "inventions" have likely been around at least as long as swingsets and male pattern baldness, respectively.:) Any utility either patent would have would therefore lie not in expressing the claimed inventions to the public and thereby advancing public knowledge, given that neither "invention" really is one, but rather purely in the short-term monopoly granted to the patent holder, and since these two "inventions" were in all likelihood both fully extant prior to being patented, the granting of such monopolies constitutes little more than a power grab, should the grantee actually seek to exercise their exclusivity rights.
On the minus side, a lot of shiat gets found too...
< sigh. > Yes, this is indeed a problem with allowing public comment. Crowd-sourcing anything, be it prior art research or Wikipedia or even democracy, will produce crap from time to time, and possibly more often than not if there is no QA mechanism. I don't suppose you have any QA mechanism ideas for the Peer2Patent process? Specifically, QA that would vet prior art references before reaching the patent examiner's desk? I can't think of anything useful off the top of my head.
Theoretically, at least, the examiners are working with new inventions, stuff no one has thought of before - it's therefore impossible for them (or anyone else other than the inventor) to be an expert on the invention already.
It might be a subtle distinction, but my concern in my previous post, and I guess in this thread in general, has more to do with patent examiners being experts in their respective fields, not necessarily being experts regarding the claimed inventions per se. Such an expert should be able to effectively evaluate any application for obviousness and prior art. While perhaps not the best example, an expert on swingsets, for instance, would realize offhand that swinging sideways is both an obvious and widely used means of deriving entertainment, and such an expert would therefore have rejected the application to patent a Method of swinging on a swing on both obviousness and prior art grounds. W.r.t. TFA itself, an expert in computer security systems should be aware of not just POSIX permissions (a red herring many others have brought up), but also capabilities (which sound much closer to what IPAT claims to do). Given that capabilities have been researched, written about, and implemented since at least around the late 1970s (KeyKOS, for example), even if IPAT's claims go beyond capabilities themselves, and would therefore not be subject to rejection on prior art grounds per se, in such a case they should be stringently evaluated for obviousness as a possibly inevitable outgrowth from or extension of capabilities. (Note that I'm not saying that such evaluation did not occur -- I have no way of knowing. I *am* saying that the existence of dubious patents such as the swingset and combover patents does raise suspicions that due diligence has not been fully carried out, for pretty much *any* patent.)
So, to restate my concerns here, I am worried that USPTO patent examiners appear to not have adequate expertise to p
Well, there seem to be two main issues, roughly speaking, that get in the way here. One would appear to be a conflict of interest, in that patent officers are apparently paid based on how many applications they complete. Since approval is a much quicker and less complicated process than rejecting, and then having to deal with refutations, patent officers have a clear incentive to approve as many patents as possible, regardless of their merit. This might be what spawned such bizarre and utility-less patents as the two I linked to previously.
What would solve this issue? Changing the pay structure. And, since the current pay structure was likely put in place precisely to incentivize moving through the patent application backlog as quickly as possible, it would no doubt behoove us as a country to increase USPTO funding to increase the number of patent examiners. At the same time, measures like Bilski to limit and more clearly define the realms of the patentable, and thereby reduce the number of applications at the source, would likely also help.
The other issue that has been discussed here on Slashdot is the simple fact that no patent office staff, no matter how large, can possibly have the expertise required to honestly and effectively evaluate the flood of multi-varied patent applications. This is a structural incompetence, and by incompetence here I don't mean "bumbling idiots" (though some no doubt would say so), I mean instead simply "not capable of performing the duties of adequately examining all patent applications".
How might this be overcome? One proposal that makes some sense has also been mentioned here on Slashdot before, and that is to open the patent examination process to comment from the public, allowing others, possibly with greater expertise in the relevant subject areas, to have some input regarding prior art and obviousness.
I'm not sure how effective these proposed changes might be, but it's clear that the current system is failing with regard to its constitutional mandate: to promote the progress of science and useful arts (Constitution, Article I). I find it fascinating that Justice Joseph Bradley, back in 1883, accurately described our current situation by extrapolating what would happen if any advancement at all, not just the notable, truly novel, and useful, were deemed patentable (emphasis mine):
The design of the patent laws is to reward those who make some substantial discovery or invention which adds to our knowledge and makes a step in advance in the useful arts. Such inventors are worthy of all favor. It was never the object of those laws to grant a monopoly for every trifling device, every shadow of a shade of an idea, which would naturally and spontaneously occur to any skilled mechanic or operator in the ordinary progress of manufactures. Such an indiscriminate creation of exclusive privileges tends rather to obstruct than to stimulate invention. It creates a class of speculative schemers who make it their business to watch the advancing wave of improvement and gather its foam in the form of patented monopolies which enable them to lay a heavy tax upon the industry of the country without contributing anything to the real advancement of the art. It embarrasses the honest pursuit of business with fears and apprehensions of concealed liens and unknown liabilities to law suits and vexatious accountings for profits made in good faith.
(source: Atlantic Works v. Brady, 107 U.S. 192 (1883))
US Supreme Court Justice William Douglas built on this argument in a written opinion in 1950 (emphasis mine):
Every patent is the grant of a privilege of exacting tolls from the public. The Framer
Partially side-stepping the question of prior art, I'm wondering about the patentability of these claims on obviousness grounds. From Wikipedia:
One of the main requirements of patentability is that the invention being patented is not obvious, meaning that a "person having ordinary skill in the art" would not know how to solve the problem at which the invention is directed by using exactly the same mechanism.
I'm certainly no patent lawyer, but an awful lot of the things we've seen coming out of the USPTO seem to fail the obviousness test on a prima facie basis, such as the infamous Method of swinging on a swing, or the Method of concealing partial baldness. It seems relatively clear that at least some of the patents being granted are failing the obviousness test. Given this background, is it reasonable to inquire whether "a person having ordinary skill in the art" of computer systems security might not find IPAT's claims to be, well, obvious as a natural extension of Unix's user-based security apparatus?
Fascinating idea -- recursive mirroring on such a scale as this...:D
Some descriptions of the universe talk about how, if you go in one direction far enough, you'll wind up back where you started. Maybe it's the same for size as well? I.e., if you get big enough, you wind up back at the small, and vice-versa. Fun thought.
Dark energy == Bogon flux. This is why scientists have been finding more evidence for dark energy and dark matter (condensed bogons) as educational standards have deteriorated and politicians have multiplied. In fact, we can all thank our failing edumacation systems and bloated governments for single-handedly (?) ensuring the Big Crunch, thereby saving us all from the heat death of the universe.
I thought Mars' thin atmosphere had less to do with gravity and more to do with the fact that Mars has much less of a magnetic field, thus allowing the solar wind to blow away what atmosphere the planet has? In fact, there was an article or two not all that long ago wherein scientists had discovered that Mars' magnetic field sometimes even paunches out, forming loops that hasten the process of atmospheric erosion.
Lemme see... Okay, here's an older article talking about how Mars has a very weak magnetic field, with the planet therefore facing the full brunt of the solar wind. And here's the more recent one that I remember, describing how Martian magnetic fields loop far out from the planet in narrow columns, ultimately pinching off big blobs of atmospheric gases far above the surface where the gases then get blown away by the solar wind. Interesting reads, both of them.
So, in a nutshell, it seems to have much less to do with gravity, and much more to do with planetary magnetic fields. Mars is afforded much less protection by its magnetic field compared to the Earth.
This is just a shot in the dark, but you haven't spent a lot of time dealing with academics, have you?
I'm not slighting you at all -- it's just that I have dealt with a number of academic eggheads, some of them even in my family, and most of them are insufferably arrogant bastards.
... but having grown up in DC, all too close to the stench of the halls of power, and all too cognizant of the squalor prevalent mere blocks away, I am far too cynical to really expect that this might be the case.
Regardless of the underlying ironic humour in the parent post, Kalriath really comes across (to me at least) more as insightful than funny. This case is another prime exemplification of how bizarre the legal situation becomes once any activity takes place via the internet, as if engaging in business online somehow changes everything (beyond just the medium of exchange).
Heh!:) That's what I mean about being like a PS2 controller on steroids -- but it's actually a lot easier to learn and deal with than the pictures alone might suggest. And as alternate-geometry keyboards go, the Alphagrip is one of the most affordable -- last I looked it was only around $99, while others were more in the ~$400-500 range. And if you're getting it for business purposes, you can always write it off on your taxes.;)
Good points. Another mouse-wise option I've found helpful is switching away from a mouse entirely, and using a Wacom tablet instead. I reasoned that handwriting everything for years growing up hadn't caused me any RSI troubles, so maybe that would work better than the cramped hand posture required for mice and trackballs -- and it seems I was right, at least for myself.
This article hardly covers *every* category. I'm a full-time translator, sometimes spending far too much time at my keyboard, and RSI is a big issue. One big help I found in working around and avoiding RSI issues is the Alphagrip.
It looks like a PS2 controller on steroids. Sure, it's a bit funky and takes a while to get used to, but its different key layout means that learning it does not overwrite your muscle memory for regular QWERTY boards, allowing you to swap back and forth with no confusion -- unlike Dvorak layouts, for instance. Plus, it's portable.:) The one drawback is no wireless version yet, but word is they're working on that. I've found the Alphagrip to be very useful in recovering from RSI induced by generic keyboards.
(Note -- I have no relation to the Alphagrip company. I am merely a satisfied customer.)
Fair enough. I suppose I'm showing some bias -- I'm one of those folks who get lost in dictionaries and encyclopedias, where cross-referencing leads me down a rabbit hole and fifteen minutes later I realize I've forgotten what I went to look up in the first place.:) Hence my preference for one-page object explanations -- I find everything I need in one place, and can read up and get back to whatever I was doing without wandering through a link tree and possibly getting sidetracked.
And you're right about Perl and Python and the man pages. Meanwhile, on the flip side, we've got OOo, Compiere / Adempiere, Plone (at least, last time I looked at it)... where the docs are sparse, hard to read through (for me anyway), or just plain missing in places.
Interesting, that -- languages and shells seem to have the best documentation, while platforms and big applications seem to have the worst. Do you see this trend too, or is it just my own limited experience?
So... what was it you were complaining about, again?
More or less, exactly what you pointed out:) -- you have to jump around through several different pages, sometimes branching through whole trees, to find out the properties and methods of one single object type. This is not easily discoverable. Sure, it's possible to find things out, but it's certainly not terribly easy nor fast. From a source code point of view, I can understand the reasons for listing which interfaces are implemented, but from an API perspective, why not include also the methods and properties themselves, all on the one page? That's easy enough to do with proper referencing and no need to duplicate content on the server, and keeps the reader from having to jump through so many hoops.
And, as you yourself note, in some cases the documentation doesn't even document things properly:
...there isn't actually any doc to describe the properties that are applicable to a TextCursor instance. 'course, the easiest answer is to hack up some test code to emit all the properties and see what's there, but that's certainly not ideal.
So again, it's possible, but neither easy nor fast. When I'm trying to get myself up to speed with either an API or a bunch of source code, the last thing I want to be doing is wasting time and energy due to poor organization of the docs.
In contrast to the maze of twisty passages that is the OOo documentation, let's look at Microsoft's documentation for the Selection object for MS Word, roughly similar in some ways to Writer's TextCursor. Here, we have all properties and methods listed on one page, with no need to click and click just to find the names of what properties and methods a Selection object has. As much as I quite dislike MS for how they conduct business, their documentation puts just about any FOSS project, and certainly OOo, to shame.
As I posted earlier in a different thread, OOo already *has* API documentation, but it sucks rocks. So rather than just providing any old documentation, I would like to exhort all FOSS people to provide sensible, usable, understandable documentation.:)
Slashdot Mirror
Oo, I like that measure. So how many is it?
Cheers,
If the amount (7 whole nutmegs?) is no exaggeration, your friend is lucky he didn't kill himself. Nutmeg is quite toxic at high doses.
And no, the list of symptoms doesn't sound like "a whole barrel-load of fun" to me either. :-P
Cheers,
You're being sarcastic, but several years ago I was living in Japan, and saw something awfully close to what you describe.
The government in the US at the time was trying to figure out what to do with the settlement of the Big Tobacco lawsuit, and many states were putting together anti-smoking campaigns. I don't know if you've ever been to Japan, but folks there are big smokers.
So some mid-level bureaucrat in the Ministry of Health and Welfare was interviewed on the evening news, and asked if the government in Japan would also be engaging in anti-smoking efforts. With a level of candour unthinkable on the other side of the pond, this fellow plainly stated that no, Japan's government would not, because smoking would help reduce the aging population and thereby limit the ultimate public expenditures required to care for a large elderly population.
Japan. What else can I say. :)
Cheers,
Reading all the responses here, it sure looks like different folks have widely different reactions to caffeine -- no big surprise, but big medical in the media has yet to understand that everyone's a bit different, and no, one size definitely does not fit all.
Anyway, the one time in my life that I *have* hallucinated was after drinking far too much of the witches' brew coffee at a local greasy spoon, the dregs of the pot that had been sitting on the burner all afternoon and had simmered down to sludge by just before closing time when we usually showed up. I had maybe half a dozen cups of that, and my friend and I were having a ball talking about all sorts of wackiness. Once the diner kicked us out to close, we went driving on back country roads like usual to catch some air in some places and continue talking.
Aside from general perceptual distortions, every time we passed a Mobil gas station, I felt like I was getting sucked into the red "O" in the signs.
All the winding roads soon made me carsick though, and we pulled over. By that point it was around 2AM or so. The local sherriff pulled over a few minutes later -- "All right boys, whaddya been drinking?"
Both of us: "Coffee! Coffeecoffeecoffeesir, toomuchcoffee!" ... It's 2AM. Go home."
Sherriff: "Huh... well, I'm'a have to give you a breathalyzer test."
(given the look on the sherriff's face, we must have scored negative values)
"Boys,
But yeah, the next day was unpleasant, even without the M&Ms. :-P
Cheers,
Can you get me in touch with these people you're advising? I could certainly use some free IT equipment.
No really, I'm serious -- if you know of folks throwing out perfectly functional computers solely because of virus infections, I'd love to have a few of their machines. Heck, they're worth something just for hobbyist spare parts, if nothing else. :)
Cheers,
Wow, some fun, interesting, and smart goings-on here at Slashdot! Oh yeah, that's why I still come here... :)
Forgive me, I should have been more explicit. I don't consider the ideas claimed to be utility-less, but rather the patents themselves, w.r.t. any advancements -- both "inventions" have likely been around at least as long as swingsets and male pattern baldness, respectively. :) Any utility either patent would have would therefore lie not in expressing the claimed inventions to the public and thereby advancing public knowledge, given that neither "invention" really is one, but rather purely in the short-term monopoly granted to the patent holder, and since these two "inventions" were in all likelihood both fully extant prior to being patented, the granting of such monopolies constitutes little more than a power grab, should the grantee actually seek to exercise their exclusivity rights.
< sigh. > Yes, this is indeed a problem with allowing public comment. Crowd-sourcing anything, be it prior art research or Wikipedia or even democracy, will produce crap from time to time, and possibly more often than not if there is no QA mechanism. I don't suppose you have any QA mechanism ideas for the Peer2Patent process? Specifically, QA that would vet prior art references before reaching the patent examiner's desk? I can't think of anything useful off the top of my head.
It might be a subtle distinction, but my concern in my previous post, and I guess in this thread in general, has more to do with patent examiners being experts in their respective fields, not necessarily being experts regarding the claimed inventions per se. Such an expert should be able to effectively evaluate any application for obviousness and prior art. While perhaps not the best example, an expert on swingsets, for instance, would realize offhand that swinging sideways is both an obvious and widely used means of deriving entertainment, and such an expert would therefore have rejected the application to patent a Method of swinging on a swing on both obviousness and prior art grounds. W.r.t. TFA itself, an expert in computer security systems should be aware of not just POSIX permissions (a red herring many others have brought up), but also capabilities (which sound much closer to what IPAT claims to do). Given that capabilities have been researched, written about, and implemented since at least around the late 1970s (KeyKOS, for example), even if IPAT's claims go beyond capabilities themselves, and would therefore not be subject to rejection on prior art grounds per se, in such a case they should be stringently evaluated for obviousness as a possibly inevitable outgrowth from or extension of capabilities. (Note that I'm not saying that such evaluation did not occur -- I have no way of knowing. I *am* saying that the existence of dubious patents such as the swingset and combover patents does raise suspicions that due diligence has not been fully carried out, for pretty much *any* patent.)
So, to restate my concerns here, I am worried that USPTO patent examiners appear to not have adequate expertise to p
Well, there seem to be two main issues, roughly speaking, that get in the way here. One would appear to be a conflict of interest, in that patent officers are apparently paid based on how many applications they complete. Since approval is a much quicker and less complicated process than rejecting, and then having to deal with refutations, patent officers have a clear incentive to approve as many patents as possible, regardless of their merit. This might be what spawned such bizarre and utility-less patents as the two I linked to previously.
The other issue that has been discussed here on Slashdot is the simple fact that no patent office staff, no matter how large, can possibly have the expertise required to honestly and effectively evaluate the flood of multi-varied patent applications. This is a structural incompetence, and by incompetence here I don't mean "bumbling idiots" (though some no doubt would say so), I mean instead simply "not capable of performing the duties of adequately examining all patent applications".
I'm not sure how effective these proposed changes might be, but it's clear that the current system is failing with regard to its constitutional mandate: to promote the progress of science and useful arts (Constitution, Article I). I find it fascinating that Justice Joseph Bradley, back in 1883, accurately described our current situation by extrapolating what would happen if any advancement at all, not just the notable, truly novel, and useful, were deemed patentable (emphasis mine):
US Supreme Court Justice William Douglas built on this argument in a written opinion in 1950 (emphasis mine):
Partially side-stepping the question of prior art, I'm wondering about the patentability of these claims on obviousness grounds. From Wikipedia:
I'm certainly no patent lawyer, but an awful lot of the things we've seen coming out of the USPTO seem to fail the obviousness test on a prima facie basis, such as the infamous Method of swinging on a swing, or the Method of concealing partial baldness. It seems relatively clear that at least some of the patents being granted are failing the obviousness test. Given this background, is it reasonable to inquire whether "a person having ordinary skill in the art" of computer systems security might not find IPAT's claims to be, well, obvious as a natural extension of Unix's user-based security apparatus?
Cheers,
Fascinating idea -- recursive mirroring on such a scale as this... :D
Some descriptions of the universe talk about how, if you go in one direction far enough, you'll wind up back where you started. Maybe it's the same for size as well? I.e., if you get big enough, you wind up back at the small, and vice-versa. Fun thought.
Cheers,
Dark energy == Bogon flux. This is why scientists have been finding more evidence for dark energy and dark matter (condensed bogons) as educational standards have deteriorated and politicians have multiplied. In fact, we can all thank our failing edumacation systems and bloated governments for single-handedly (?) ensuring the Big Crunch, thereby saving us all from the heat death of the universe.
Whee.
I thought Mars' thin atmosphere had less to do with gravity and more to do with the fact that Mars has much less of a magnetic field, thus allowing the solar wind to blow away what atmosphere the planet has? In fact, there was an article or two not all that long ago wherein scientists had discovered that Mars' magnetic field sometimes even paunches out, forming loops that hasten the process of atmospheric erosion.
Lemme see... Okay, here's an older article talking about how Mars has a very weak magnetic field, with the planet therefore facing the full brunt of the solar wind. And here's the more recent one that I remember, describing how Martian magnetic fields loop far out from the planet in narrow columns, ultimately pinching off big blobs of atmospheric gases far above the surface where the gases then get blown away by the solar wind. Interesting reads, both of them.
So, in a nutshell, it seems to have much less to do with gravity, and much more to do with planetary magnetic fields. Mars is afforded much less protection by its magnetic field compared to the Earth.
Cheers,
This is just a shot in the dark, but you haven't spent a lot of time dealing with academics, have you?
I'm not slighting you at all -- it's just that I have dealt with a number of academic eggheads, some of them even in my family, and most of them are insufferably arrogant bastards.
Cheers,
... but having grown up in DC, all too close to the stench of the halls of power, and all too cognizant of the squalor prevalent mere blocks away, I am far too cynical to really expect that this might be the case.
May I be proved wrong.
Oh, but for some mod points right now! I grew up in DC... suffice it to say that I generally agree with you. :-\
Cheers,
Regardless of the underlying ironic humour in the parent post, Kalriath really comes across (to me at least) more as insightful than funny. This case is another prime exemplification of how bizarre the legal situation becomes once any activity takes place via the internet, as if engaging in business online somehow changes everything (beyond just the medium of exchange).
Cheers,
It's important to note that the big push that sent Rome toppling came in the form of climate change.
Guess what? The weather's changing...
Cheers,
Well put, sir!
Cheers,
Thankfully, not terribly familiar, but now that you mention it, I catch your reference -- more's the pity! :-P
Apologies for being too literal minded, :)
Heh! :) That's what I mean about being like a PS2 controller on steroids -- but it's actually a lot easier to learn and deal with than the pictures alone might suggest. And as alternate-geometry keyboards go, the Alphagrip is one of the most affordable -- last I looked it was only around $99, while others were more in the ~$400-500 range. And if you're getting it for business purposes, you can always write it off on your taxes. ;)
Cheers,
Interesting -- what do you think it is about the Apple USB keyboard design that has helped you?
Curious,
Good points. Another mouse-wise option I've found helpful is switching away from a mouse entirely, and using a Wacom tablet instead. I reasoned that handwriting everything for years growing up hadn't caused me any RSI troubles, so maybe that would work better than the cramped hand posture required for mice and trackballs -- and it seems I was right, at least for myself.
Cheers,
This article hardly covers *every* category. I'm a full-time translator, sometimes spending far too much time at my keyboard, and RSI is a big issue. One big help I found in working around and avoiding RSI issues is the Alphagrip.
It looks like a PS2 controller on steroids. Sure, it's a bit funky and takes a while to get used to, but its different key layout means that learning it does not overwrite your muscle memory for regular QWERTY boards, allowing you to swap back and forth with no confusion -- unlike Dvorak layouts, for instance. Plus, it's portable. :) The one drawback is no wireless version yet, but word is they're working on that. I've found the Alphagrip to be very useful in recovering from RSI induced by generic keyboards.
(Note -- I have no relation to the Alphagrip company. I am merely a satisfied customer.)
Cheers,
Fair enough. I suppose I'm showing some bias -- I'm one of those folks who get lost in dictionaries and encyclopedias, where cross-referencing leads me down a rabbit hole and fifteen minutes later I realize I've forgotten what I went to look up in the first place. :) Hence my preference for one-page object explanations -- I find everything I need in one place, and can read up and get back to whatever I was doing without wandering through a link tree and possibly getting sidetracked.
And you're right about Perl and Python and the man pages. Meanwhile, on the flip side, we've got OOo, Compiere / Adempiere, Plone (at least, last time I looked at it)... where the docs are sparse, hard to read through (for me anyway), or just plain missing in places.
Interesting, that -- languages and shells seem to have the best documentation, while platforms and big applications seem to have the worst. Do you see this trend too, or is it just my own limited experience?
Cheers,
More or less, exactly what you pointed out :) -- you have to jump around through several different pages, sometimes branching through whole trees, to find out the properties and methods of one single object type. This is not easily discoverable. Sure, it's possible to find things out, but it's certainly not terribly easy nor fast. From a source code point of view, I can understand the reasons for listing which interfaces are implemented, but from an API perspective, why not include also the methods and properties themselves, all on the one page? That's easy enough to do with proper referencing and no need to duplicate content on the server, and keeps the reader from having to jump through so many hoops.
And, as you yourself note, in some cases the documentation doesn't even document things properly:
So again, it's possible, but neither easy nor fast. When I'm trying to get myself up to speed with either an API or a bunch of source code, the last thing I want to be doing is wasting time and energy due to poor organization of the docs.
In contrast to the maze of twisty passages that is the OOo documentation, let's look at Microsoft's documentation for the Selection object for MS Word, roughly similar in some ways to Writer's TextCursor. Here, we have all properties and methods listed on one page, with no need to click and click just to find the names of what properties and methods a Selection object has. As much as I quite dislike MS for how they conduct business, their documentation puts just about any FOSS project, and certainly OOo, to shame.
Cheers,
As I posted earlier in a different thread, OOo already *has* API documentation, but it sucks rocks. So rather than just providing any old documentation, I would like to exhort all FOSS people to provide sensible, usable, understandable documentation. :)
Cheers,