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.
So why a browser extension instead of a mirror site (like APIdock)? Because I don’t want to scrape content just to show it on another website. There’s too much to scrape, and too much to keep up to date. And if that website became popular but later became unmaintained (like APIdock), it might hurt Apple’s SEO. Plus, I don’t want AI crawlers to scrape the notes.
I thought about moderation, and my naive view is that we don’t need heavy moderation. For a spammer, downloading the extension, creating an account, and verifying their email are just too much hassle. Also, users can upvote helpful notes and downvote unhelpful ones, and notes that get too many downvotes will disappear. I think this simple system should be enough to weed out most of the spam.
I bought technotesapp.com and wrote a Rails backend from scratch instead of using services like Disqus or GitHub Discussions. I set up SMTP integration for verification emails, drafted the terms of service and privacy policy, and did it all just so I could control how the notes look and style them to match Apple’s design.
Even though the notes are HTML and CSS, I try my best to follow the HIG. This means controls have clear focus indicators, text fields look like text fields, and buttons look like buttons. I try to make the notes blend into the documentation pages, down to using the same syntax-highlighting colors. For the extension and website, I have more freedom with the design, so the UI is more Mac-assed.
I announced the TestFlight two weeks ago, and so far the feedback has been… crickets. Not many people have joined, and even fewer have created notes. Still, with just a handful of notes, I can already see the potential of this project. I hope things will pick up soon. If you develop for Apple platforms, please join the TestFlight, sign up, and post your first Technote.