{"id":562,"date":"2010-09-07T16:36:22","date_gmt":"2010-09-08T00:36:22","guid":{"rendered":"http:\/\/www.visophyte.org\/blog\/?p=562"},"modified":"2011-01-10T14:27:51","modified_gmt":"2011-01-10T22:27:51","slug":"documentation-for-complex-things-you-dont-basically-already-understand","status":"publish","type":"post","link":"https:\/\/www.visophyte.org\/blog\/2010\/09\/07\/documentation-for-complex-things-you-dont-basically-already-understand\/","title":{"rendered":"Documentation for complex things (you don\u2019t basically already understand)"},"content":{"rendered":"

\"\"<\/a><\/p>\n

The Problem<\/h3>\n

One of my focuses at MoMo<\/a> is to improve the plight of Thunderbird<\/a> extension developers.\u00a0 An important aspect of this is improving the platform they are exposed to.\u00a0 Any platform usually entails a fair amount of complexity.\u00a0 The trick is that you only pay for the things that are new-to-you, learning-wise.<\/p>\n

The ‘web’ as a platform is not particularly simple; it’s got a lot of pieces, some of which are fantastically complex (ex: layout engines).\u00a0 But those bits are frequently orthogonal, can be learned incrementally, have reams of available documentation, extensive tools that can aid in understanding, and, most importantly, are already reasonably well known to a comparatively large population.\u00a0 The further you get from the web-become-platform, the more new things you need to learn and the more hand-holding you need if you’re not going to just read the source or trial-and-error your way through.\u00a0 (Not that those are bad ways to roll; but not a lot of people make it all the way through those gauntlets.)<\/p>\n

I am working to make Thunderbird more extensible in more than a replace-some-function\/widget-and-hope-no-other-extensions-had-similar-ideas sort of way.\u00a0 I am also working to make Thunderbird and its extensions more scalable and performant without requiring a lot of engineering work on the part of every extension.\u00a0 This entails new mini-platforms and non-trivial new things to learn.<\/p>\n

There is, of course, no point in building a spaceship if no one is going to fly it into space and fight space pirates.\u00a0 Which is to say, the training program for astronauts with all its sword-fighting lessons is just as important as the spaceship, and just buying them each a copy of “sword-fighting for dummies who live in the future” won’t cut it.<\/p>\n

Translating this into modern-day pre-space-pirate terminology, it would be dumb to make a super fancy extension API if no one uses it.\u00a0 And given that the platform is far enough from pure-web and universally familiar subject domains, a lot of hand-holding is in order.\u00a0 Since there is no pre-existing development community familiar with the framework, they can’t practically be human hands either.<\/p>\n

\"\"<\/a><\/p>\n

The Requirements<\/h3>\n

I assert the following things are therefore important for the documentation to be able to do:<\/p>\n