Hacker News Reader

Comment by modeless | Hacker News Reader

Yeah the state of Chrome's extension API documentation is awful. It needs to be totally reorganized and partially rewritten. I'm hopeful that MDN will become a better resource as Firefox becomes more compatible with the APIs. It's already more helpful in some places.

View on HN

All of Google's documentations are awful.

I spent a few days on a pet project using the Google Sheets API and the official docs use a mix of 3 different versions of libraries, none of which are really up to date, and you have to guess which is the right one.

They don't care about developers.

They put in quite some effort into writing the docs but then they often leave them to rot. Broken links and invalid code.

You'd have thought that a company the size of Google would have their public documentation problem totally solved by now.

It's more than just good stuff rotting. It's a fundamental lack of care, or maybe inability to ship anything that represents a big iteration. On the Google Analytics side, they are preparing to turn off data collection from the existing version of Analytics in 6 months and have been telling everyone to migrate to the new version for months now - but their "migration guides" are missing crucial technical detail, fall out of sync with the state of the new product a mere month or so after publishing, or contradict each other. It's like the whole effort of documentation has just been outsourced to the world of blogspam. Meanwhile, they started aggressively pushing for users to migrate their data collection when the new product itself didn't support some of the most basic use cases that needed to be migrated. Something is just off with Google's ability to ship these days.

Funny, I've been using the MDN docs and took a look at the Chrome docs today. Some of the conceptual info was easier to track on the Chrome docs where the Mozilla side seemed to jump too low level too quickly.

Ideally, those docs should just be in one place so writing Chrome/Safari/Firefox extensions should just work.

> the Mozilla side seemed to jump too low level too quickly

This is literally my only complaint about MDN, and it’s only a complaint when I’m in a hurry. The sprawling body of standards MDN documents are almost all fairly low level and intended as such, and MDN mostly does a good job of balancing the low level details with good boilerplate examples. I can’t say how this is for extensions on any version, but if the MDN docs continue apace I’d be surprised if they don’t at least adequately answer this “should” as shortly behind a stable spec as anyone could wish for.

I wish XML-related tech was such a hot documentation commodity… guess I better contribute as I go :)

Hey! What things related to xml are you working on? I for one went through the signing and stuff and it was pretty rough going.

I maintain the Enketo[1] projects for ODK[2]. The latter is a little more flexible and stable on the XML front, but the former is currently in the position of using a lot of nonstandard XML tooling despite being well positioned to use existing browser tech, and at the same time may be better off migrating to many of the same abstractions ODK already uses.

1: https://github.com/enketo

2: https://github.com/getodk

Reply on news.ycombinator.com