I can’t count that high

Writing No Comments

I just read that, every year, around 60,000 books are published in the USA. That’s 160 or so every single day.

I don’t really have anything useful to say about this, it just blew my mind. If 60,000 are published, how many are submitted to publishers and rejected? Good heavens.

Thinking about Print

Work, Writing 16 Comments

Every once in a while I get mail from someone asking for a downloadable version of one or another “books” from the MDC Wiki. Since last March, I’ve got this request less than a dozen times, but it’s something I occasionally sit and try to bend my brain around.

There are many questions involved.

The first (and key) question is: Is there enough demand for a downloadable version of, say, the JavaScript 1.5 Reference, to invest a lot of time/effort into producing it? I don’t know the answer to this at the moment, so I’ll ask you: how often do you find yourself in a situation where you want to look something up but can’t because you’re offline and can’t access the MDC wiki?

That aside, the real difficulty begins. By the very nature of wikis, they are malleable. The MDC wiki content changes daily with new edits, corrections, additions, page moves, and deletions. I think that the wiki has, in fact, changed several times every day since it was first launched last March. This is a very powerful feature of the wiki, in that it’s easy to make changes and improvements, and so people do. I might be mistaken, but I’m fairly certain that the MDC currently hosts the most up-to-date version of a JavaScript reference currently in existence (warts and all).

The complicated bit here is that in order to maintain a completely up-to-date downloadable/printable version of any particular collection of content within the wiki, the process of generating that content would have to be wholly automated. One would think that computers would be good at that sort of thing, but evidence appears to show otherwise. I’m certainly not the first or smartest person to think about this problem, and as far as I can tell every other project started towards a solution has been abandoned well before completion.

(Aside: if you know of a current and/or complete project that does what I’m talking about, be it wiki->PDF or wiki->docbook or wiki->xml, please send me a note.)

The good folk over at the Hula project have sort of addressed this issue with their Single Page Administration Guide (warning: it’s a long page…164 pages when saved to PDF). Using wiki includes, they’ve simply collated all the disparate pages into a single long page, which you can then print or save to PDF or what-have-you.

This include-everything-in-a-single-page trick is an OKish solution, in that it does allow people to get a copy of the content that they can then use offline. There are also problems. The table of contents has no page numbers. The page section headings don’t have numbers, so the section numbers in the TOC aren’t very useful. Links aren’t clickable (or even rendered as links) so things like “see Message Store” in the HTML version show up simply as “see Message Store” in the PDF. And so forth.

I think the trick will be figuring out how to turn wiki pages into DocBook XML fragments (using only a simple subset of DocBook elements), then patching those fragments together into full DocBook books. Once the DocBook book is available, there are a host of different tools that can be used to generate it into a variety of formats, including much-more-useful PDFs.

While that seems simple enough on the surface, the number of dead projects that have attempted to do this in a fully automated fashion seems to indicate otherwise.

So, if it can’t be fully automated, could it be partially automated? Could wiki markup be turned into a rough approximation of DocBook fragments which could then be finessed and pieced together by hand?

This is where the first question becomes important. If this requires human intervention, is it worth doing at all? Would it be worth the effort to generate a DocBook version of the JavaScript Reference once or twice per year given that it will be rendered almost immediately obsolete by updates to the wiki?

I don’t know. Maybe. Maybe not. What do you think? Is it worth it? Is there an easy way to do this wiki->DocBook or wiki->PDF generation that would generate a proper book without requiring a lot of human involvement?

The wiki has been an awesome boon for the state of Mozilla developer documentation. In less than a year over 22000 edits and additions have been made, each of which has served to improve the content we deliver. The web version of the content is XHTML compliant (with occasional markup errors in editing), and it’s relatively usable and friendly with a nice layout. The kicker is trying to turn this incredible resource into usable offline formats. Obviously we don’t want to stop using the wikis, so if we want to generate offline content, we have to figure out how to do that given the tools at our disposal.

And this is apparently what I spend my Friday evenings thinking about.

A language rant

Language, Ranting, Writing No Comments

Nothing like a good language rant to start the day off right.

I have a (another) new blog

Books, Ramblings, Writing 6 Comments

Faithful readers! All, like, four of you. You’ll be excited to learn that I’ve started yet-another-weblog. I’ve been intending to start this one for a while, but having a couple of days off has finally given me the time to get it done-enough to start using. It’s over here:

Parchment Moon

Parchment Moon is a weblog about books, writing, language, and other literary things. Mostly books, tho’. Anyhow. There you go.

Jed’s Other Poem (Beautiful Ground)

Art, General, Music, Writing No Comments

Jed wrote poems. Here’s one that was turned into a music video, described as “[a]n unsolicited music video for the band Grandaddy and their song of the same name off of the album The Sophtware Slump“. The punchline? Programmed in Applesoft II on a 1979 Apple ][+ with 48K of RAM. Seriously. It’s brilliant. Seriously.

Ah, Friday

General, Writing No Comments

Canadians seem to have it bred into them that the Friday before a long weekend is actually part of the weekend, and is thus only sort of a pretend work day, if it actually turns out to be a work day at all. This is a hard habit to break, even if you love your job (as I do) and have a whole lot of stuff to get done (as I do). I did manage to make it clear through to 2:30pm before cracking a Mike’s and calling it a day, which isn’t so bad. The best part is that I managed to finish up a particularly irksome bit of work that needed to be done, so that won’t be hanging over my head come Monday.

Monday, of course, is a holiday in Canada, but I’ll end up working part of it since the rest of the world are a bunch of no-long-weekend suckers. Note that I am thus utterly remorseless about a few hours of slackery this afternoon.

Tonight’s fit of writing clocked in at 2048 words, and was largely an exploratory piece about two odd characters who have been poking around my brain for the last few days. It turns out that they actually fit into the story of another character I sketched out recently. Interesting. They’ve even managed to wrap a setting around themselves, so I know where they live, what they do, and what the general environment around them is like.

What’s strange is that everything every writer has ever said about how characters tell you their stories once you start to get into them is absolutely true. (You’d think that after reading it the first 30-40 times I might start to believe it.) One character was born out of a single line of dialogue. I wrote that at the top of the page, then just continued the rest of the scene. That scene turned into another scene which eventually turned into four pages of exploration where she told me all sorts of crazy things about herself. She brought with her a somewhat odd history, a couple of other characters, and an entirely plausible way that she fits in with the other characters I have recently discovered. This is all somewhat unexpected in that when I wrote that line of dialogue at the top of the page, I thought I was working on something in a completely different genre than where it ended up.

Turns out, writing is a hell of a lot of fun.

On Writing, and Other Things

Books, Ramblings, Writing 3 Comments

I have a new regimen. This is a different regimen than my new “do a half-hour of circuit training three times per week” regimen. This is a more intellectual pursuit, and it consists of three parts.

The first part is that I have started writing again. The plan is this: one thousand words per day, minimum, outside of weblogs and personal journals. The trick here is that the subject matter has to be different. No blithering on for one thousand words about the random crap with which I filled my day. No talking about websites or games or other random crap I found on the internet. This is supposed to be more exploratory stuff — fiction, non-fiction, whatever. Exploration into realms about which I do not normally write. Delving deep into memory and self to carve out pieces and put those on paper. It’s actually a lot less cliche than it sounds.

I’ve been on this new regimen for three days now. The first day I managed to get twenty-one hundred words out before I faltered and fell silent. Day two was seventeen-hundred words. Day three (just now) was another seventeen-hundred. I’m not allowed to cheat, either. If I do two thousand words on one day, it doesn’t mean I get out of the one thousand words the next. Minimum one thousand words, every day. Maximum: unlimited. No carryovers. No touchbacks. Tag.

It has been interesting so far, in that I’ve already found myself thinking about what I could write about at various points throughout the day. I could write about my childhood heros, perhaps, or my recently acquired love of cooking. Maybe I could put out a thousand words about Zen and what it means to me, or at least how I interpret it (which, for what it’s worth, is probably quite unlike what any real Zen student would tell you). How about how I learned to love reading and language? Maybe a piece about my utter disdain for current advertising and marketing and how they’re missing the boat by trying to lie to us incessantly, bombarding us with blipverts that we simply Do Not Believe (seriously, guys, your audience is smarter than you think). I could easily churn out one thousand words about joining a (women-only) gym and starting a new workout regimen (don’t let anyone tell you for even a second that women are less competitive than men). A thousand words about the death and secret rebirth of television as a medium for storytelling. A thousand words about my first trip to the local library (which I haven’t yet done). When I think of it, I jot these ideas down for later retrieval, but haven’t needed to use them yet.

When I actually sit down to write, of course, all bets are off. As yet, there has been no pre-planning. Tonight’s Daily (I’m calling them Dailies) started off with a somewhat vociferous rant against Margaret Atwood which churned itself into a thousand words about Canadian Culture. Yesterday was about cooking, food, dinner parties, and some reflections thereupon. The day before was (quick pause while I go check) about embracing change, later turning into a bit about the strange clash between horror and beauty that we all endure every single day. None of these topics were preselected — they just happened to be what poured out of my brain and into the keyboard while I had the word processor open to a blank page.

Naturally, the vast majority of what I’ve written is utter trash. Breathless at times, totally disorganized, wholly unrevised. Just raw. But that’s ok. For now, that’s all I want — I just want to get into the habit of producing a certain amount of raw content on a daily basis. Writing, you see, has two phases. Generating raw content is, by necessity, the first. The second, which can only happen once the raw content is available, is revising. Unlike sculptors, writers don’t start with a block of material and just spend their time taking away the parts that don’t belong. We need to create the block first, and only then can we start chipping away at the edges. Right now, I just need to produce giant chunks of rough marble.

The second part of my new writerly regimen is this, my weblog. In addition to the one thousand word not-for-other-people minimum, I intend to spend ten to fifteen minutes churning out an entry for my weblog (not including revision and additions). This has two purposes. First, it will mean my weblog gets updated daily, which I’m hoping will draw in more readers. Behind this interminably timid exterior, I really do crave an audience. Second, it will get me used to the idea of actually writing for an audience every day. The one thousand word minimum is all well and good, but if I don’t get used to the idea of having other people actually read my writing, I’ll eventually end up cheating by typing the word “house” a thousand or more times, until the word itself becomes utterly nonsensical and loses all meaning. So, yeah. The weblog entries are intended to keep me at least partially anchored in reality. Writers write to be read. Anything else is just intellectual wanking.

The third and final part of my new regimen involves reading. I used to read a lot. Books upon books every week. I had no TV, I wasn’t caught up in the whole gaming craze, I wasn’t yet jacked into the Matrix (read: Internet). I had a lot of hours to fill, and I gleefully filled them with books. In bulk. When I lived in Montreal I would spend $300-$500 every paycheque on books, often going downtown daily just to browse the bookshops.

Then I stopped reading. Not entirely of course, but from a diet of three or four books per week, I ended up down to about one per month, usually read in ten page increments right before bed. That’s no damned good. I love reading, and so I’m going to make time for it again. I don’t have a minimum daily allotment, but I’d like to be able to spend a couple of hours every day, on average, just sitting on my butt with a book.

And with that, I think I shall.

(43 mins, including revision. 1056 words. So much for 10-15 mins.)

Common Errors in English

Writing No Comments

Common Errors in English Usage. Ever want to know whether it’s “jerry-rigged” or “jury-rigged”? How about when to use “who” instead of “that”? Or, my new favourite, Colons and Semicolons.

While you’re here, you might as well go read George Orwell’s essay, “Politics and the English Language“.

On Writing Well

Writing 2 Comments

Five points if you know the book from which I’ve stolen this title, and five bonus points if you’ve read it. I’m going to go dig up a copy of it later today (assuming I find a free hour in the afternoon to go to the bookstore). It will be my airplane reading next week, assuming I manage to actually get an eticket-enabled flight.

Writing well — like photography, music, martial arts and all other such disciplined human endeavours — is difficult and requires a lot of practice. I need to practice more. I write a lot, but due to the nature of the media I’m usually writing in, I tend not to revise rigorously. Email, weblogs, wikis — all of these are built for speed. Here we have rocket engines and racing stripes on our pens. Disciplined revision is tossed aside as email are dashed off at top speed. Brevity and concision take time, and so are abandoned to the wolves snapping at our heels. Churning out copy by the truckload is fast and easy — the raw materials effortlessly fall out of our heads and into the keyboard — but shaping that material into something of quality is much, much more difficult. These media also allow everyone to be a publisher, so there are few gatekeepers to remind us that sometimes quality counts.

I’m overstating the issue, of course, but the combination of new media and high-speed lifestyles simply encourages quantity over quality. Just this morning I sent out an email that contains a seemingly random comma. It’s just there, right in the middle of a sentence, exactly where a comma shouldn’t be. Had I taken the time to revise properly, that comma would have been extracted before I embarrassed myself in front of dozens of people. I can only hope that everyone reads that mail as quickly as I wrote it.

Writing well takes time, so in order to improve my writing (and photography) I’m going to have to find more time. To find more time, I’m going to have to do fewer things while not letting the remaining things expand to fill all available space. This is where real discipline will be required.

If you’re also interested in improving your writing, you might want to make some time to read these: Fifty Writing Tools.

For the language geeks in the audience…

Writing No Comments

A Handbook of Rhetorical Devices.

Icons by N.Design Studio. Designed By Ben Swift. Powered by WordPress and Free WordPress Themes
Entries RSS Comments RSS Log in