Feed aggregator
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.Google's New Hurricane Model Was Breathtakingly Good This Season
Read more of this story at Slashdot.
Google Removed 749 Million Anna's Archive URLs From Its Search Results
Read more of this story at Slashdot.
Apple Brings Its App Store To the Web
Read more of this story at Slashdot.
Data Breach At Major Swedish Software Supplier Impacts 1.5 Million
Read more of this story at Slashdot.
The World's Tallest Chip Defies the Limits of Computing: Goodbye To Moore's Law?
Read more of this story at Slashdot.
Apple Delays Home App Update Requirement Until February 2026
Read more of this story at Slashdot.
Google's Next Moonshot Is Putting TPUs In Space With 'Project Suncatcher'
Read more of this story at Slashdot.
New HDR10+ Advanced Standard Will Try To Fix the Soap Opera Effect
Read more of this story at Slashdot.
Windows 10 Update Incorrectly Tells Some Users They've Reached End-of-Life, Despite Having Extended Support
Read more of this story at Slashdot.
Ferrari Aims at AI Generation With Crypto Auction For Le Mans Car
Read more of this story at Slashdot.
IBM To Cut Thousands of Roles in Focus on Software Growth
Read more of this story at Slashdot.
Ex-Cybersecurity Staff Charged With Moonlighting as Hackers
Read more of this story at Slashdot.
