Slashdot Mirror
Microsoft Documentation Declared Unfit For US Consumption
anomalous cohort writes "Washington DC judge Colleen Kollar-Kotelly announced during the ongoing Microsoft antitrust hearings that their documentation is unfit for US consumption. This is relevant in an antitrust hearing as poor documentation on how to inter-operate with Microsoft's products is seen as an unfair barrier to entry for companies who compete with Microsoft. Others see this as yet another example of their crumbling hegemony or indolence as their empire burns."
I agree with what you said but at the same time the site is more unbiased than people think.
If any company is doing something poorly being unbiased doesn't mean attack and promoting those bad habits. It means reporting fact. Fact doesn't always give both sides because there isn't two sides to give and the fact is Microsoft does a lot of stupid stuff. The consumer doesn't always see (or care about) this stuff so some articles come off as biased attacks on Microsoft in those people's eye.
I'm sure there are. And the saddest part of this is that with all those people doing the best they can, every Microsoft product is a bloated, buggy mass of security holes.
Good, inexpensive web hosting
Article submitter:
anomalous cohort (http://www.dynamicalsoftware.com/)
From the marketing "blog" linked in the summary (http://www.dynamicalsoftware.com/cgi-bin/ViewBlogEntry.pl?id=14)
writing and maintaining developer documentation is an important part of any software development project [...] Another reason for documentation is compliance management [...] our collaborative software development project lifecycle management product Code Roller supports compliance management [...]
Nice try!
Let my new 7-digit UID be a lesson to all - write down your passwords.
That kind of attitude quite naturally leads to contempt for documentation. Now, I've never worked at Microsoft, so I don't know what their documentation habits are like, but I suspect they are as poor as in most companies.
Now, of course many companies do produce got user documentation, but that kind of writing can be done effectively by a skilled technical user who is also adept at documentation. The problem here at hand is the programming guide. Making your software inter-operable comes very close to writing such a guide.
Howver, skilled writers are rarely involved in writing such guides. The work is left to the programmers themselves. That's like leaving the fox in charge of the henhouse. Programmers have a natural inclination to not describe their techniques clearly.
"If the code was hard to write, it should be hard to read! We're not going to reveal our secrets without a fight!"
As another comment below suggests, most likely the inter-operability docs never existed in the first place: the documents presented to the EU courts were, most likely, reverse-engineered from the code itself!
IANAL, because I have two more semesters of law school to complete. Before that, I was a computer science major.
Your mistake is that you are comparing legal code to software documentation. However, the more apt comparison is to compare legal code to software source code, at which point your analogy fails. While they aren't widely advertised, there are plenty of secondary sources (such as legal encyclopedias) out there that make law accessible to a layman.
I'm a lawyer, but not yours. I wouldn't represent someone who thinks taking legal advice from Slashdot is a good idea.
The best non-FOSS documentation I have used lately is Oracles.
Example for the 10G starting directory
Aside from the actual WORKING search functionality (which gives you a list in of "books" in which the search term occured with numbers of hits first, so that you can go to the relevant "book" when the search term is something ambiguous like "format" instead a long list of maybe or maybe not relevant links).
I never found the right thing on MSDN unless I stumble upon it via a Google search, Oracle usually gives the Description of a feature, some overview where it is uses and some examples with each feature. So once you are on the HTML page of the particular feature you are interested in you basically can get all the Information from that single page. Take for example a direct comparison between the commands to format a number into a string.
to_char (Oracle) found in about 20 seconds on the web page itself either by browsing by function or searching.
After two minutes I managed to get here in MSDN trying to find the command to format numbers in SQL Server, but haven't found the exact command yet, only an overview about "string functions" but the right one doesn't seem to be in this category.
I even know the command is "format".. something, but I cant browse there directly, since I don't know in what CATEGORY in those open/closable subdirectories they put it in.
The quickly scrollable and searchable HTML indexes of Oracle's online help are much easier to manage.