Feed aggregator
72% of Game Developers Say Steam Is Effectively a PC Gaming Monopoly
Read more of this story at Slashdot.
Gemini AI To Transform Google Maps Into a More Conversational Experience
Read more of this story at Slashdot.
New Bipartisan Bill Would Require Companies To Report AI Job Losses
Read more of this story at Slashdot.
43% of Gen Z Prefer YouTube and TikTok To Traditional TV and Streaming
Read more of this story at Slashdot.
Danish Authorities In Rush To Close Security Loophole In Chinese Electric Buses
Read more of this story at Slashdot.
T-Mobile Brings Free 911 Emergency Texting To AT&T and Verizon Customers
Read more of this story at Slashdot.
Windows 11 Store Gets Ninite-Style Multi-App Installer Feature
Read more of this story at Slashdot.
Smartphone Maker Nothing Retreats on Bloatware After User Backlash
Read more of this story at Slashdot.
Solar Geoengineering in Wrong Hands Could Wreak Climate Havoc, Scientists Warn
Read more of this story at Slashdot.
Deutsche Bank Explores Hedges For Data Centre Exposure as AI Lending Booms
Read more of this story at Slashdot.
China Bans Foreign AI Chips From State-Funded Data Centres
Read more of this story at Slashdot.
Epic and Google Settle Antitrust Case With Global Fee Cuts and Easier Third-Party Store Access
Read more of this story at Slashdot.
Kodak Quietly Begins Directly Selling Kodak Gold and Ultramax Film Again
Read more of this story at Slashdot.
World Economic Forum Chief Warns of Three Possible 'Bubbles' in Global Economy
Read more of this story at Slashdot.
Europe's Self-Driving Cars Aren't Even at the Starting Line
Read more of this story at Slashdot.
Brazil Proposes a New Type of Fund To Protect Tropical Forests
Read more of this story at Slashdot.
DRAM Costs Surge Past Gold as AI Demand Strains Supply
Read more of this story at Slashdot.
Trump Re-Nominates Billionaire Jared Isaacman To Run NASA
Read more of this story at Slashdot.
China Achieves Thorium-Uranium Conversion Within Molten Salt Reactor
Read more of this story at Slashdot.
Future Documentation
Dotan was digging through vendor supplied documentation to understand how to use an API. To his delight, he found a specific function which solved exactly the problem he had, complete with examples of how it was to be used. Fantastic!
He copied one of the examples, and hit compile, and reviewed the list of errors. Mostly, the errors were around "the function you're calling doesn't exist". He went back to the documentation, checked it, went back to the code, didn't find any mistakes, and scratched his head.
Now, it's worth noting the route Dotan took to find the function. He navigated there from a different documentation page, which sent him to an anchor in the middle of a larger documentation page- vendorsite.com/docs/product/specific-api#specific-function.
This meant that as the page loaded, his browser scrolled directly down to the specific-function section of the page. Thus, Dotan missed the gigantic banner at the top of the page for that API, which said this:
/!\ NOTE /!\ NOTE /!\ NOTE /!\ NOTE /!\ NOTE /!\ NOTE /!\ NOTE /!
This doc was written to help flesh out a user API. The features described here are all hypothetical and do not actually exist yet, don't assume anything you see on this page works in any version
/!\ NOTE /!\ NOTE /!\ NOTE /!\ NOTE /!\ NOTE /!\ NOTE /!\ NOTE /!\
On one hand, I think providing this kind of documentation is invaluable, both to your end users and for your own development team. It's a great roadmap, a "documentation driven development" process. And I can see that they made an attempt to be extremely clear about it being incomplete and unimplemented- but they didn't think about how people actually used their documentation site. A banner at the top of the page only works if you read the page from top to bottom, but documentation pages you will frequently skip to specific sections of the page.
But there was a deeper issue with the way this particular approach was executed: while the page announced that one shouldn't assume anything works, many of the functions on the page did work. Many did not. There was no rhyme or reason, to version information or other indicators to help a developer understand what was and was not actually implemented.
So while the idea of a documentation-oriented roadmap specifying features that are coming is good, the execution here verged into WTF territory. It was a roadmap, but with all the landmarks erased, so you had no idea where you actually were along the length of that road. And the one warning sign that would help you was hidden behind a bush.
Dotan asks: "WTF is that page doing on the official documentation wiki?"
And I'd say, I understand why it's there, but boy it should have been more clear about what it actually was.
[Advertisement] Keep the plebs out of prod. Restrict NuGet feed privileges with ProGet. Learn more.