Technotes Safari Extension
Zhenyi Tan (via Kyle Howells):
A few months ago, I posted this image on Mastodon, because the Apple documentation website sometimes feel… err, underwhelming. Many people have already pointed this out, so I won’t repeat their complaints. When people complain about Apple’s documentation, they often compare it to php.net, saying that php.net has sample code for almost every function and community notes that explain details when the code alone isn’t enough.
So I thought, what if we just make Apple’s documentation more like php.net? I posted the question on Mastodon, but not many people were interested. Oh no! Anyway, two months later, I decided to give it a shot because I still thought the idea was good enough to try. I then called it Technotes.
Technotes is a Safari extension that adds user-contributed notes to the Apple documentation website. The notes can include sample code, warnings about common pitfalls, and other useful stuff.
1 Comment RSS · Twitter · Mastodon
This is a great idea, but the problem with all of these approaches of in-place supplementing of documentation and commenting, is one of critical mass.
Until enough people use the same tool to add notes or provide open feedback etc, then it becomes non-useful in the majority of use cases.
Not sure how to solve this problem unless the owner of the documentation is involved..
Perhaps a better approach – with our existing fragmented landscape of supplemental information and AI – is to have a tool that provides in-place supplementation of documentation, such as Apple's documentation website, but gathered from existing web & social sources.
Imagine a tool that somehow supplements Apple's API with context specific information from across the web; e.g the top related Q&As from StackExchange, the top How-tos from Hacking With Swift etc. All perfectly organised by API and OS version, along with related open feedbacks and issues on the API being used. It could then provide immediate value-add for most use cases and solve the chicken and egg, critical mass issue.
Or perhaps. AI coding tools will just mean that developers don't need documentation in the future at all! Or, perhaps not :)
